Install Shadowrocket on Linux: DEB, RPM, or AppImage

Check your distribution, architecture, and download options

Package formats determine how software is managed by your system; they don't determine proxy protocols or connection speeds. Debian, Ubuntu, and compatible distributions typically use DEB packages. Fedora typically uses RPM. If no native package is available, check whether an AppImage will work in your environment. The file extension alone doesn't guarantee compatibility: RPM-based distributions can have different dependencies.

Run these commands in a terminal first. The first shows your distribution's ID, ID_LIKE, and related details; the second shows your machine architecture. The package architecture on the download page must match your system. Common architectures such as x86_64 and aarch64 aren't interchangeable. If the download page doesn't list a matching architecture, don't force-install a package built for another one.

cat /etc/os-release
uname -m

• Debian / Ubuntu: Choose a DEB package for your architecture from the download page, then use apt to install it and handle dependencies.
• Fedora: Choose an RPM package for your architecture and install it with dnf. For other RPM-based distributions, follow your package manager's requirements and compatibility guidance.
• Other desktop distributions: Check the AppImage architecture and runtime requirements. AppImages aren't guaranteed to work in every Linux environment.

DEB: install a local package with apt

After downloading the DEB from the download page, open a Bash terminal and run these two commands. When prompted, paste the downloaded file's full absolute path and press Enter. Don't add quotation marks to the input. The double quotes in the command preserve spaces in the path so the filename isn't split into multiple arguments.

read -r -p 'Paste the full absolute path to the DEB file: ' pkg
sudo apt install "$pkg"

Use the actual file path, such as the location shown in your file manager—not just the filename. apt can install a local DEB and resolve dependencies from your configured software sources. If you use only dpkg -i, missing dependencies may leave the package unconfigured. For a first-time installation, apt makes it easier to review the complete result.

1. Review the packages apt plans to install, upgrade, or remove. Confirm only after checking that it won't remove an unexpectedly large number of packages.
2. When installation finishes, search for Shadowrocket in your desktop's application menu and launch it as a regular user.
3. If you see an unmet dependencies error, note the full message and your distribution details. Don't bypass it by forcing the installation to ignore dependencies.

Download progress in the terminal doesn't mean installation succeeded. Check apt's final exit status. If the command ends with an error, fix the software source, network, or dependency issue before trying to launch the app.

RPM: use dnf on Fedora

After downloading an RPM built for your architecture, Fedora users can enter its path in Bash using the same method. dnf handles the local package and any dependencies from your system's software sources in one transaction. Avoid force-install options that skip dependency checks.

read -r -p 'Paste the full absolute path to the RPM file: ' pkg
sudo dnf install "$pkg"

Installing a local RPM doesn't necessarily mean the process is fully offline: missing dependencies may still need to be downloaded from enabled software sources. If a download times out, check that your software sources are available. If the architecture doesn't match, choose another package instead of repeatedly running the install command.

• File not found: Check that you entered the complete path. Don't include the terminal prompt or extra quotation marks when pasting it.
• Unmet dependencies: Confirm which distribution the package targets. Don't install core libraries from another distribution without checking compatibility.
• Execution blocked by policy: Keep the specific error or security event details and troubleshoot your distribution's security policy. Disabling the entire security system isn't a standard fix.

AppImage: make it executable and run it

AppImages usually aren't registered as installed software through apt or dnf. Move the file to a fixed directory you can manage, then grant your user permission to execute it. If you move the file later, update any desktop shortcuts that still point to its old location. The commands below don't change permissions for the entire directory.

read -r -p 'Paste the full absolute path to the AppImage file: ' app
chmod u+x "$app"
"$app"

The last command runs the file in the current terminal, so you can see any error output if it fails to launch. Don't use sudo to test permissions by starting the entire graphical app as root. Execute permissions, filesystem mount options, and system authorization for connections are separate issues.

If the terminal reports a FUSE error, install the appropriate runtime support using your distribution's documentation, or switch to a compatible native package. If the file is on a filesystem mounted with noexec, it may not run even after chmod. Move it to a user directory that allows execution and try again.

First launch: import your subscription and check routing

Seeing the app window only confirms that the graphical program has launched; it doesn't prove that your subscription works or that system traffic is being routed through it. During installation, address file and dependency issues. In the app, check your subscription, selected node, Global Routing, and system authorization separately. The steps below use interface labels such as Home, Config, and Settings to help you find each option. Layouts may vary by platform, so follow the options available in your current interface.

1. Open the app

   Launch Shadowrocket from your application menu or AppImage file. Make sure the window opens normally. If the system requests network-related authorization, check the app name and requested access before approving.

2. Add a subscription

   Go to Home → + → Type → Subscribe, paste your existing subscription link, and save it. The link contains access credentials, so don't include the full URL in screenshots or support requests.

3. Update the list

   On Home, update the subscription and check that nodes appear. The example https://example.com/sub?token=xxxx illustrates the format; it isn't a working subscription.

4. Choose a policy

   Select an existing node. Before using rule-based routing, check the active configuration in Config, then set Global Routing to Config. When testing, note the selected node and routing mode.

5. Test the connection

   Turn on the connection, visit the target page, and check the available connection logs. Confirm that requests reach the app and match the expected policy; the enabled toggle alone doesn't prove the connection is working.

Use the address, port, password, and TLS settings provided by your own service provider; don't change them to 443 at random for testing. Settings → On Demand controls conditional connections; it isn't a way to fix installation dependencies. Configure it only if the feature is available on your platform and you need it. For initial troubleshooting, connect manually so automatic connection conditions don't affect the results.

Which Global Routing mode should you use after installation?

The package format doesn't choose a routing policy for you. For everyday use, check the configuration first, then choose a routing mode. These options are settings within Shadowrocket and apply to requests handled by the app. They don't show that all traffic from every Linux process is being routed through a proxy.

For example, to proxy requests to a sample domain and connect directly for everything else, use a snippet like this in the configuration's Rule section. This demonstrates rule syntax only and doesn't include a node. Back up your current configuration before applying it, and confirm that the proxy policy referenced by PROXY is available.

[Rule]
DOMAIN-SUFFIX,example.com,PROXY
FINAL,DIRECT

DOMAIN-SUFFIX matches a domain and its subdomains. Rules are checked from top to bottom; FINAL handles requests that didn't match anything earlier, so put FINAL at the end of the rules. If Config behaves differently from Proxy, check which rule matched instead of reinstalling the app. For more on routing modes and configuration fields, see Proxy modes and Configuration fields.

FAQ: launch issues, updates, and uninstalling

Uninstall native packages with apt remove or dnf remove, but look up the package name first. To remove an AppImage, quit the process and delete the file and any shortcuts you created. These steps don't necessarily remove configuration files in your user directory. Before switching installation formats, save any configuration you need and avoid running two instances at once, which can make it harder to tell which connection or settings are active.