This guide is for Linux devices with a desktop environment. Check your distro and CPU architecture first, then choose a Shadowrocket package from this site’s download page: Debian and Ubuntu usually use deb; Fedora and other dnf-based systems use rpm; choose AppImage if you want a standalone file. The steps below cover installing a local file, setting execute permissions, troubleshooting launch errors, and checking for updates. Connection setup assumes you already have your own provider and subscription.
1. Check your distro and architecture before choosing a package
The Linux package format for Shadowrocket determines how files are managed and dependencies are handled; it does not determine protocol support. Don’t choose a file based on its extension alone: check that the distro, CPU architecture, and system requirements listed on the download page all match. AppImage reduces reliance on distro-specific package formats, but one file won’t necessarily run on every architecture or system.
Run these commands in order in a terminal. The first displays your distribution details; the second reports the machine architecture. If the output is x86_64, check that the download is labeled for x86-64. If it is aarch64, look for an ARM64 build. If the download page has no matching package, don’t try to install another one by changing its file extension.
cat /etc/os-release
uname -m| System | Package format | How it works |
|---|---|---|
| Debian, Ubuntu, and compatible systems | deb | Install the local file with apt and resolve dependencies. |
| Fedora and other dnf-based systems | rpm | Install the local file with dnf and resolve dependencies. |
| Other RPM-based distributions | rpm | Check compatibility first and use the distro’s own package manager; don’t assume dnf commands will work. |
| Want to keep a standalone file | AppImage | Check the architecture and runtime requirements, grant execute permission, then launch it. |
Get packages from the Linux section of the downloads page; use the files actually listed there. The Linux version is free. The iPhone and iPad version costs $2.99 as a one-time App Store purchase; the Mac (Apple silicon / Intel), Windows, and Android versions are also free. Download methods vary by platform, so use the one listed for your device.
2. Complete these four checks before downloading
The steps below separate choosing a package from setting up a connection. If the installer launches, that only confirms that the basic local runtime requirements are met; connecting still depends on your existing server parameters, network, and routing settings. For a first-time setup, don’t enable automatic network handling yet. That makes installation issues easier to distinguish from connection issues.
-
Check your system
Run
cat /etc/os-releaseanduname -mto note your distribution and architecture. The interactive commands below are written for Bash; runbashfirst if needed to enter that shell. -
Get the file
Open this site’s download page → Linux and choose a listed deb, rpm, or AppImage for your system. Once the download finishes, locate the file in your file manager. Don’t pass an incomplete download to the installer.
-
Install and launch
Install or run the file using the command in the next section. Launch the app as a regular user the first time. Only system operations such as package installation require administrator privileges; don’t use
sudoto launch the entire desktop app. -
Import and test
Go to Home → “+” → Type → Subscribe and enter your existing subscription, then save and update it. Select an available configuration and check Global Routing before connecting as needed. A successful import does not prove that every destination is reachable.
3. Install deb with apt or rpm with dnf
These commands don’t assume a package filename. When prompted in the terminal, paste the absolute path to the file you just downloaded and press Enter. Don’t add quotation marks around the path. The "$pkg" variable in the command handles spaces in the path. If your file manager’s “Copy location” gives you a file:// URL, convert it to a local file path before using it.
Debian / Ubuntu: install a local deb file
read -r -p 'Enter the absolute path to the deb file: ' pkg
dpkg-deb -f "$pkg" Package Architecture
sudo apt install "$pkg"The dpkg-deb line reads the package name and architecture so you can check them again before installation. apt install takes a local file path, not a remote package name; it will try to resolve dependencies using your configured repositories. If dependencies are missing, check your system repositories and network first. Don’t force installation by ignoring dependencies or adding unfamiliar repositories.
Fedora and other dnf systems: install a local rpm file
read -r -p 'Enter the absolute path to the rpm file: ' pkg
rpm -qp --queryformat '%{NAME} %{ARCH}\n' "$pkg"
sudo dnf install "$pkg"rpm -qp only reads metadata from the specified file; dnf handles the installation. Review the transaction summary before confirming. Cancel if it proposes removing many system components or shows an architecture mismatch or dependency conflict. Other RPM-based distributions may not include dnf, and their packages may not be compatible; check the download page first.
- File not found: Check the path, capitalization, and whether the download finished. A web address is not a local file path.
- Architecture mismatch: Compare
uname -mwith the package metadata and choose the right file. Renaming a package won’t change its architecture. - Dependencies can’t be satisfied: Check distro compatibility and repository status. Don’t treat skipping dependency checks as a successful installation.
4. Grant AppImage execute permission, then run it as a regular user
An AppImage is usually kept as a single file and is not registered in the apt or dnf package database. You can move it to a fixed location in your home directory, then grant it execute permission. Avoid running it from a browser’s temporary folder, where cleanup could remove it. Run the commands below in Bash and enter the file’s actual absolute path.
read -r -p 'Enter the absolute path to the AppImage file: ' app
chmod u+x "$app"
"$app"chmod u+x grants execute permission to the file owner only. There’s no need to make the file writable by everyone. If double-clicking does nothing, running it from a terminal makes errors easier to spot. For Permission denied, check both the execute bit and whether the filesystem is mounted with noexec. Some removable drives and restricted directories won’t allow execution even after you add the execute bit.
Handle FUSE errors according to your distribution. Some AppImage runtimes require FUSE support. If the terminal reports a missing library or a mount failure, check your distribution’s package documentation and install the appropriate component. Don’t blindly use package names from another distribution or remove existing FUSE components.
AppImage also requires a graphical session and a compatible system runtime. In a terminal-only server, container, or SSH session without a desktop, an executable file may still be unable to display a graphical window. If you see an error such as cannot open display, troubleshoot from your local desktop session instead of repeatedly running installation commands.
5. After launch, distinguish installation, subscription, and routing issues
Once the window opens, make sure Home, Config, and Settings work, then import your existing connection details. The protocol and server parameters must match: Shadowsocks, VMess, VLESS, Trojan, Hysteria2, and WireGuard are not interchangeable labels. Changing a configuration’s Type to a different protocol won’t fix a mismatch with the server.
When troubleshooting, distinguish among these three Global Routing settings. The traffic described here is limited to connections handled by Shadowrocket; it does not mean that every app and protocol on Linux is automatically routed through it. Check the configured conditions for Scene to see what actually applies; don’t infer a connection’s route from the scene name alone.
Config
RuleRoutes connections according to the rules in the current configuration. Rules such as DOMAIN-SUFFIX, IP-CIDR, and GEOIP are used for matching. The final route also depends on rule order and FINAL; a connection that doesn’t match a rule is not necessarily sent direct.
Use when: You have a verified split-routing configuration and are ready for everyday use.
Proxy
Sends all connections entering the processing chain through the selected proxy policy. This can help distinguish rule-matching issues from proxy-path issues, but you still need to confirm that the selected server and protocol parameters are valid.
Use when: Briefly troubleshooting rules or policy selection in Config.
Direct
Sends connections entering the processing chain directly to their destinations without a proxy server. This is useful for establishing a baseline for your local network, but it won’t test whether a proxy server is working.
Use when: Checking whether local DNS, your network route, and the destination itself are working.
For an initial test, change only one setting at a time. Note the current Global Routing setting, switch it temporarily, and test the same destination again. Restore the original setting when done. On Demand controls when connections are triggered; it doesn’t fix installation problems. For initial troubleshooting, check the conditions under Settings → On Demand to prevent automatic connections from changing the test results.
6. Common installation and launch problems
I downloaded a deb file. Why won’t it open on Fedora?
Run cat /etc/os-release first to identify your system. deb and rpm belong to different package-management systems; changing the file extension won’t make them interchangeable. Return to this site’s download page and choose a compatible rpm, or check the AppImage requirements. Don’t install another package manager just to get around a format mismatch.
I ran chmod on the AppImage, but it still won’t execute. Why?
Run ls -l "$app" to check whether the file owner has execute permission, then compare the architecture with uname -m. For Permission denied, check whether the filesystem is mounted with noexec. For Exec format error, check for an architecture mismatch or incomplete file first; adding more permissions won’t help.
The window opens, but Home has no connection profiles. Is the installation broken?
No connection profiles doesn’t mean the installation failed. Use your own provider and subscription: go to Home → “+” → Type → Subscribe to add and update it, or enter your existing parameters manually. This site only explains how to configure subscriptions you already own; it does not supply connection services. After importing, check the protocol, server port, and authentication fields.
My browser works, but terminal commands aren’t using the proxy. What should I check?
Check the app’s proxy settings, how system traffic is handled, and the proxy environment variables for the terminal process. Terminal tools may not use the desktop system proxy. If a tool needs an explicit proxy address, check the actual listening address, port, and protocol in your current settings instead of guessing a default port. Troubleshoot Linux permissions and traffic routing separately from package installation.
7. What to keep before updating, rolling back, or uninstalling
Installing a local deb or rpm doesn’t automatically add an update repository. For future updates, return to this site’s download page, check the available package, and use the same package manager. If you change package formats, make sure the old process has exited first. Otherwise, desktop menu entries, old files, and new files may coexist and make it unclear which copy is launching.
- Keep your configuration: Check the active configuration in Config and save it using the export or backup option available in the interface. Note the connection profile in use on Home and your Global Routing setting.
- Record custom settings: Note any listener addresses, ports, DNS settings, and routing policies you changed. Don’t store backups containing passwords, private keys, or subscription credentials in a public directory.
- Update deb / rpm: Download the new file for your architecture, then run the corresponding installation command above. Review the package manager’s transaction summary and check the affected packages and dependency changes before proceeding.
- Update AppImage: Exit the old process and keep the old file. Put the new file in a fixed directory and grant it execute permission again. If you created a desktop launcher, check that its target points to the new file.
- Before uninstalling: Remove deb / rpm packages with your package manager, using the actual package name from the installation file’s metadata. To remove an AppImage launch entry, delete the AppImage and any launcher you created. User configuration may remain, so check it separately.
After updating, compare the same known destination using the same connection profile and routing settings. A window that opens is not enough to confirm network functionality. Check the subscription update, connection, and actual access results to distinguish app runtime issues from configuration issues.