This guide is for users installing Shadowrocket on a Linux desktop who already have a service provider and subscription. Check your distro and CPU architecture first, then choose a DEB, RPM, or AppImage. After installation, verify that the app launches, the subscription imports, and requests connect—so you can distinguish installation issues from configuration problems.
1. Check your distro, architecture, and package format
DEB, RPM, and AppImage are different ways to distribute Linux software, not different proxy protocols. Choose a package based on your distro’s package manager, then check the architecture and system requirements listed on the download page. Renaming a file from .rpm to .deb won’t convert its format or fix an architecture mismatch.
Open a terminal and run these commands. /etc/os-release identifies your distro, while uname -m reports your architecture. Check both separately; a desktop’s appearance isn’t enough to identify them.
cat /etc/os-release
uname -m
| Format | Commonly used on | How to install or run | Keep in mind |
|---|---|---|---|
| deb | Debian, Ubuntu, and derivatives that use apt | Install the local file with apt | Registers the package with the package manager, which resolves dependencies from configured repositories. |
| rpm | Fedora and distros that use dnf | Install the local file with dnf | Using RPM format doesn’t mean every distro uses dnf. |
| AppImage | Linux desktops that meet the file’s runtime requirements | Make executable, then run | Still depends on CPU architecture, system libraries, FUSE, and mount options. |
For example, x86_64 often corresponds to x64 or amd64 on the download page, while aarch64 often corresponds to arm64. These are architecture naming conventions, not a guarantee that every combination is available. Check the all-platform download page for available files. Repeatedly adding execute permissions won’t fix an architecture mismatch.
2. Download the file and note its details
Select Linux on the download page, then choose a format for your distro. Get files through this site’s download page; there’s no need to construct a package URL yourself. Note the download folder and the exact filename—you’ll need them to install the package, troubleshoot issues, and check package details.
-
Check your system
Open a terminal, run the two commands from the previous section, and note your distro and architecture. A remote terminal may be connected to a different system than your desktop, so confirm which machine you’re working on.
-
Choose a format
Go to the Linux section of the all-platform download page. Choose DEB for systems using apt and RPM for systems using dnf. If you’re considering AppImage, check its runtime requirements first.
-
Note the file path
In your file manager, view the file’s properties and copy its full path. When a terminal prompt asks for the path below, enter it without extra quotation marks; don’t use an unexpanded tilde in place of your home directory.
-
Check the download
Confirm the file came from this site’s download page and finished downloading. If the filename still has a temporary browser download suffix, wait for the download to finish before installing. Don’t remove the suffix manually and try to run the file.
3. Install the DEB or RPM, or run the AppImage
Run the commands below in Bash, using only the set that matches your chosen format. Each command prompts for the actual file path, so there’s no assumed package filename. Double quotes around the variable preserve spaces in the path. Close Shadowrocket before installing.
DEB: Let apt handle the local package and dependencies
Run these commands on an apt-based system such as Debian or Ubuntu. After entering the file’s absolute path, review apt’s proposed installation, upgrade, or removal actions before confirming. Don’t use a force-install option just to bypass a dependency error.
read -r -p "Enter the absolute path to the DEB file: " pkg
dpkg-deb -f "$pkg" Package Architecture
sudo apt install "$pkg"
dpkg-deb outputs the package name and architecture, which you can use to check the file you selected. If apt reports missing dependencies, first check that your system’s repositories are available. To refresh the package index, run sudo apt update, then try again. Refreshing the index doesn’t upgrade the whole system or automatically resolve incompatible distro requirements.
RPM: Install a local package on a dnf-based system
Run this set on Fedora and other systems that use dnf. It checks the package details, then lets dnf resolve dependencies. If your system uses RPM format but not dnf, use its own package manager instead of switching tools just to copy this command.
read -r -p "Enter the absolute path to the RPM file: " pkg
rpm -qp --queryformat '%{NAME} %{ARCH}\n' "$pkg"
sudo dnf install "$pkg"
If you see nothing provides, check the dependency name that follows and verify your system’s requirements and enabled repositories. Don’t force the installation by ignoring dependencies; a registered package doesn’t guarantee that the libraries needed to run it are available.
AppImage: Make it executable, then run it
Put the file somewhere your regular user can access and where it won’t be routinely cleaned up, then run these commands. AppImage isn’t registered with apt or dnf, so it won’t automatically appear in the package manager’s update or uninstall options when first launched.
read -r -p "Enter the absolute path to the AppImage file: " pkg
chmod u+x "$pkg"
"$pkg"
chmod u+xadds execute permission for the file’s owner only; there’s no need to grant all users write access.- Run it as a regular user. If no window appears, don’t try launching the entire graphical app with
sudo. - Keep the file after it runs successfully. If you create a desktop shortcut, point it to the file’s actual location.
- An AppImage can bundle application files, but that doesn’t mean all data is stored in the same folder or that every system dependency is included.
4. After the first launch, check configuration and connectivity separately
A window opening only confirms that the app launched; it doesn’t mean your subscription, server, or routing rules are configured. Check the app in this order: use Home to review the connection and servers, Config to confirm the active configuration, and Settings to review relevant options. If the system asks for network access, read the prompt before approving it.
In the app
- Home
- Check the imported servers and the one currently selected.
- Config
- Confirm which configuration and Rule section are enabled.
- Global Routing
- Check whether the current mode is Config, Proxy, or Direct.
- Connectivity Test
- Test the selected server, then verify an actual request.
Change one setting at a time and note its previous state so you can assess the result.
On your system
- CPU architecture
- Compare the output of uname -m with the architecture listed on the download page.
- System clock
- Check the time zone and date; significant errors can affect TLS verification.
- Network access
- First confirm that your regular connection works, including any network sign-in page.
- Server port
- Use the details from your provider; don’t assume every protocol uses port 443.
System internet access and proxy connectivity are separate checks; one doesn’t confirm the other.
If you already have a subscription, tap “+” in the upper-right corner of Home to open the add screen. Set Type to Subscribe, enter the subscription URL from your provider, and save. Then update the subscription and confirm that servers appear on Home. A subscription update usually refreshes server details; it shouldn’t be assumed to replace all routing rules in Config.
When adding a server manually, don’t mix fields for Shadowsocks, VMess, VLESS, Trojan, Hysteria2, and WireGuard. Enter the protocol, address, port, and authentication details exactly as provided by your service provider. A subscription URL isn’t a server address for any one protocol. Before sharing troubleshooting details, hide subscription tokens, passwords, and Private Key values.
5. Use Global Routing to separate installation issues from routing issues
If some sites work and others don’t after installation, check Global Routing before reinstalling. The options below describe how Shadowrocket handles traffic; their scope depends on which traffic reaches the app. Proxy doesn’t necessarily capture every process on the system.
Config
RecommendedHandle requests according to the active configuration. Check the order and policies in the Rule section, and see which rule the destination matches. This is a suitable everyday mode once your rules are configured correctly.
Best for: everyday routing by domain and IP address.
Proxy
Handle requests that reach the app in proxy mode. This can temporarily help rule out the effect of routing rules. If the behavior changes after switching modes, investigate the configuration rather than assuming the system installation is broken.
Best for: briefly troubleshooting rules and policy selection.
Direct
Handle requests as direct connections, without forwarding them through a proxy server. Use this to check the underlying network. If a destination requires a proxy, failure in this mode doesn’t show that the server is unavailable.
Best for: comparing direct network access with proxy connectivity.
In Config, DOMAIN-SUFFIX matches domain suffixes, IP-CIDR matches IP address ranges, GEOIP matches by IP geolocation, and FINAL provides the final fallback. Rules are generally checked from top to bottom. If an earlier rule already matches a destination, changing a later rule won’t affect that request. Back up the current configuration before editing, and restore temporary diagnostic settings after testing.
6. Common first-launch errors and how to troubleshoot them
When troubleshooting, keep the full error message and the steps that triggered it—not just “it won’t open.” The issues below are common categories for installing and running Linux apps, but won’t occur on every distro. Check file execution and dependencies first, then app configuration, and finally the specific request.
AppImage says “Permission denied” even though the download is complete. What should I do?
First run chmod u+x "$pkg" on the actual file, then launch it from the same terminal. If it still fails, run findmnt -T "$pkg" -o TARGET,OPTIONS to check whether its filesystem has the noexec option. If it does, move the file to a user directory where execution is allowed; don’t change system mount settings.
I get “Exec format error.” Is this a permissions problem?
First check the file format or architecture; adding permissions usually won’t help. Compare uname -m, the architecture listed on the download page, and the output of file "$pkg". If file reports an HTML document, you may have downloaded an error page. Return to the download page and get the correct file.
AppImage reports that libfuse.so.2 is missing. What should I install?
Note the full error, then use your distro’s package search tool to find the FUSE-compatible runtime library that provides the file. Package names can vary by distro and release; don’t remove existing FUSE components. After installing the matching dependency, launch the app from a terminal as a regular user.
Clicking the icon does nothing. How can I find out why?
For an AppImage, run the file in a terminal using the path variable from above. For a DEB or RPM installation, check the actual launch command in your desktop launcher’s properties, then run it in a terminal. Note any output about missing libraries, the graphical session, or permissions. Don’t guess the executable’s name or disable security features without a reason.
The installation succeeded, but why does the subscription update still fail?
First confirm that regular network access works, the system clock is correct, and the subscription URL contains no extra spaces or line breaks. Then check that the subscription is active with your provider. If only one subscription fails, start by checking that URL and its network route; reinstalling the app usually won’t fix an expired token.
7. What to keep when updating or uninstalling
For updates, get a file with the same architecture and a suitable format from this site’s download page. DEB and RPM upgrades are generally handled by the corresponding package manager based on package metadata. For an AppImage, close the app, replace the file, and check its execute permission and any shortcut paths. Placing a file in your downloads folder won’t automatically update the app.
- Before updating, back up any Config files you edited and note the active configuration and Global Routing mode.
- Keep the original configuration details from your provider. Treat subscription URLs, passwords, and keys in backups as sensitive information.
- Before removing a DEB or RPM package, check its actual package name. Then use apt or dnf to remove it, reviewing the confirmation list before proceeding.
- Deleting an AppImage doesn’t remove user configuration. Before clearing data, confirm its actual storage location; don’t delete directories based on guessed paths.
- After updating, check in this order: launch the app → review Home → confirm Config → test a request. This helps pinpoint where behavior changed.
Choose a format that fits your system’s package management: use the appropriate DEB on apt-based systems and RPM on dnf-based systems. With AppImage, you’re responsible for checking the file location, permissions, and runtime dependencies. After installation, configure the subscription and connection using details from your service provider.