This guide is for users with a Linux desktop environment who are ready to install Shadowrocket. First, identify your distribution and processor architecture, then choose a deb, rpm, or AppImage from this site's download page. Follow the relevant installation or launch steps, then check Home, Config, and Global Routing. Commands use the actual path to your downloaded file, not a fixed filename, and keep each package format's instructions separate.
Check your distribution and architecture first
Package format and processor architecture are separate considerations. deb and rpm determine which tools your system uses to manage software; architectures such as x86_64 and aarch64 determine whether the program can run on your processor. A matching file extension does not guarantee a compatible architecture. Open a terminal and run these two commands to identify your distribution and architecture.
cat /etc/os-release
uname -mID and ID_LIKE in /etc/os-release help identify your distribution family. uname -m typically returns a value such as x86_64 or aarch64. On the download page, x64 and amd64 usually correspond to x86_64, while arm64 usually corresponds to aarch64. Choose only an architecture actually offered on the download page that matches your system; converting package formats will not fix an architecture mismatch.
| System | Recommended format | How to install or run |
|---|---|---|
| Debian, Ubuntu, and compatible distributions | deb | Use apt to install the local package and resolve dependencies |
| Fedora and other distributions using dnf | rpm | Use dnf to install the local package and resolve dependencies |
| Other compatible Linux desktop environments | AppImage | Grant execute permission, then run as a regular user |
Being part of the rpm family does not mean every distribution uses dnf. If your system does not have dnf, do not copy Fedora's commands. AppImage is not compatible with every distribution either; it still depends on processor architecture, system libraries, and the desktop environment. This guide assumes a graphical desktop. A window that cannot appear in a remote terminal does not mean the package is damaged.
Package formats and where to get them
Visit the Shadowrocket download page and choose a Linux package, then check its file extension after saving it. This guide does not assume a fixed filename; the commands below require the actual path to the downloaded file. Wait for the download to finish before running any commands. A file with a temporary download extension is not a complete package.
Get Shadowrocket for iPhone / iPad from the App Store for a one-time $2.99 purchase. The developer is Shadow Launch Technology Limited; check the App Store listing for system requirements. The Mac version (Apple silicon and Intel), Windows, Android, and Linux versions are free; download their installers from this site's download page. Shadowrocket is closed-source commercial software; the Linux version being free does not change its licensing model.
Choose based on your system's package manager
Use deb / rpm
- Your system has a compatible package manager.
- You want the system to track the package and its dependencies.
- You can authorize administrator access during installation.
Use AppImage
- The download page offers a file for your architecture.
- You want to keep the program file in your personal directory.
- You can check execute permissions and runtime requirements yourself.
If a matching deb or rpm is available, prefer your system's package manager. AppImage runs as a standalone file, but that does not eliminate all system dependencies.
Install a deb with apt
On Debian, Ubuntu, and similar systems, use apt to install a local deb package. Unlike extracting the package manually, apt attempts to resolve dependencies from your enabled software sources. Run the lines below in order in the same Bash terminal. Enter the path without adding quotes; you can use an absolute path or one relative to the current directory.
read -r -p 'Enter the actual path to the downloaded deb file: ' pkg
pkg=$(realpath -- "$pkg")
dpkg-deb -f "$pkg" Package Architecture
sudo apt update
sudo apt install "$pkg"The dpkg-deb line only reads the package name and architecture; it does not install anything. Check that the output is what you expect before running the next commands. realpath converts the input to an absolute path so apt can identify it as a local file. If the file cannot be found, fix the path before running the install command.
-
Locate the file
Use your file manager to find the downloaded deb and note its full path. If your download folder is not named Downloads, use the folder where the file was actually saved.
-
Check the architecture
Compare the Architecture reported by
dpkg-deb -fwith your system architecture. If they do not match, return to the download page and choose a compatible package; do not use a force-install option. -
Install the package
Run the apt command and review the list of packages to be installed, upgraded, or removed. If it proposes removing many system components, cancel and check that your distribution is compatible.
-
Launch Shadowrocket
Once installation finishes successfully, launch Shadowrocket from your desktop's application menu. Do not run the entire graphical application with sudo as a substitute for the authorization flow during your first connection.
Install an rpm with dnf
On a system that uses dnf, installing a local rpm also requires the actual file path. First inspect the package information, then let dnf handle the transaction. These commands are independent of the previous section; you can use them in a new terminal by entering the file path again.
read -r -p 'Enter the actual path to the downloaded rpm file: ' pkg
pkg=$(realpath -- "$pkg")
rpm -qp --queryformat '%{NAME} %{ARCH}\n' "$pkg"
sudo dnf install "$pkg"Use rpm -qp to query a local package that has not been installed. dnf displays dependencies, downloads, and a transaction summary; review them before proceeding. If dependencies cannot be found, check your network connection and system software sources. Do not disable dependency checks as a routine installation step.
- Architecture mismatch: Return to the download page and choose a package that matches
uname -m. - File not found: Check for extra quotes, spaces, or an incorrect directory.
"$pkg"in the command already handles spaces in the path. - Package conflict: Note the conflicting package name and check whether another package format of the same application is already installed. Do not use a force-overwrite option.
- dnf is not installed: Check your distribution's instructions for installing a local rpm, or choose a compatible AppImage from the download page.
Installing deb and rpm packages may require an internet connection to retrieve dependencies. Downloading the main package does not prepare an offline installation. If dependencies are missing, resolve access to your software sources instead of repeatedly downloading the same file.
Run an AppImage for the first time
An AppImage is usually a single file. After downloading it, move it to a personal directory where you plan to keep it. It is not a deb or rpm package and cannot be installed with apt or dnf. Before the first run, grant execute permission for your user, then launch the file directly.
read -r -p 'Enter the actual path to the AppImage file: ' app
app=$(realpath -- "$app")
chmod u+x -- "$app"
"$app"chmod u+x grants execute permission only to the file's owner; there is no need to grant everyone write access. Keep the terminal open while the program runs so you can see any startup errors. Normally, run it as your current desktop user. Do not switch to administrator privileges just to get past an error.
- Permission denied: First confirm that the file belongs to your user and has execute permission, then check whether the filesystem is mounted with
noexec. If so, move the file to a personal directory where execution is allowed. - Exec format error: Check the architecture and make sure the download has completed. Adding execute permission cannot fix an architecture mismatch.
- FUSE error: Some AppImage runtime modes depend on FUSE. Follow your distribution's instructions to install the appropriate component; do not reuse package names from another system.
- No graphical display: Launch the application from a local desktop session. A terminal accessed only over SSH may not be able to display application windows.
If double-clicking the file only opens a “Choose an application” dialog, run it from the terminal using the commands above to distinguish a permission issue from a file-association issue. Whether an AppImage is added to the application menu automatically depends on desktop integration; no menu icon does not mean the file cannot run. If you move the file, existing shortcuts may stop working, so update their target paths.
Check the connection after installation
An application window confirms that the program launched, but not that a proxy connection works. The steps below assume you already have your own service provider and subscription: add your existing server details or subscription in Home, check the configuration you want to use in Config, then review Global Routing. Installation format and network mode are separate; switching to AppImage usually will not fix an error in your rules.
Config
RecommendedRequests handled by the active configuration follow its rules. Before use, confirm that Config has the expected configuration enabled and check where the final FINAL rule sends traffic.
Best for: Everyday use with a correct configuration when you need to route traffic by domain or IP address.
Proxy
Sends all traffic handled by the configuration through the proxy policy. This can help distinguish a server connection issue from a rules issue; it does not mean every process is automatically routed.
Best for: Temporarily checking whether the proxy route works. Restore your usual mode after testing.
Direct
Handles intercepted traffic as direct. Accessing regular websites in this mode does not prove that the proxy server is working.
Best for: Checking your local network and comparing it with the proxy route.
For example, the following rules in Config send example.com and its subdomains through PROXY, and send other unmatched requests through DIRECT. This illustrates rule syntax; it is not a server configuration and does not create a working connection. When troubleshooting, first check which rule actually matched, then verify its policy. Do not import this snippet as a complete configuration file.
[Rule]
DOMAIN-SUFFIX,example.com,PROXY
FINAL,DIRECTInstallation and update FAQs
apt says it cannot find the file, but I downloaded it. Why?
First locate the file in your file manager, then rerun the command that prompts for its path. Enter the file's actual path, not the download page URL. You can enter a path containing spaces as is; do not add another set of quotes yourself. Continue with installation only after confirming that the file exists and the download is complete.
Why won't my AppImage open, even after I granted permission?
Run the file from a terminal and read the error message. Check, in order, the architecture, execute permission, mount options, FUSE, and runtime libraries. If the error identifies a missing system library, follow your distribution's package instructions. Do not disable system security features and hope for the best.
Do deb and rpm packages update automatically with the system?
Installing a local package does not automatically add a software source. If you have not confirmed that an update source is configured, return to this site's download page for a compatible package and install it using the same package manager. For AppImage, quit the program, replace the file with the newly downloaded version for your architecture, and check its execute permission again.
Should I delete my configuration before reinstalling?
Do not start troubleshooting by deleting your configuration. Back up existing configurations and subscription details first, then identify whether the issue occurs at startup, during import, or when connecting. System packages and user configuration are usually stored separately; uninstalling a package is not a reliable way to back up or clean up configuration data.
After installation, note your distribution, architecture, package format, and any specific error messages. This information is more useful for troubleshooting than “the Linux version won't open.” Before sharing logs, remove subscription tokens, passwords, and private server details. Change one setting at a time so you can tell which change affected the result.