This guide covers Linux package selection, checking CPU architecture, local installation commands, and first-launch checks for Shadowrocket. Install DEB and RPM packages with the appropriate system package manager. AppImage requires execute permission and a compatible runtime environment. The steps assume you already have a service provider and subscription: install the app first, then check configuration and network connectivity separately.
1. Check Your Distribution Before Choosing a Package
Choose a package based first on your distribution's package management system, then on your CPU architecture. The desktop environment isn't a reliable guide: systems running GNOME or KDE may use DEB or RPM packages underneath. Open a terminal and run these commands to identify your system.
cat /etc/os-release
uname -m
In /etc/os-release, ID identifies the current distribution, while ID_LIKE can help indicate its distribution family. uname -m prints the machine architecture. Common values include x86_64 for 64-bit x86 (sometimes labeled amd64 on download pages) and aarch64 for 64-bit ARM (sometimes labeled arm64). Use the architectures listed for the actual downloads; don't choose based on the file extension alone.
| System | Package format | Install or run | Check first |
|---|---|---|---|
| Debian, Ubuntu, and related distributions | deb | Install a local package with apt | Package architecture and dependencies |
| Fedora and other distributions using dnf | rpm | Install a local package with dnf | Distribution compatibility and dependency sources |
| Other compatible Linux desktop environments | AppImage | Grant execute permission, then run | CPU architecture, runtime libraries, and mount options |
An RPM package isn't guaranteed to work on every system that uses the RPM format. For example, don't copy dnf commands directly on distributions that use a different package management frontend. AppImage also isn't a self-contained container completely independent of the system. If required runtime libraries are missing, the app may still fail to launch even after you grant execute permission.
2. Download the File and Note Its Path
Go to the all-platform downloads page, find the Linux packages, and choose the format and architecture based on the previous section. This guide doesn't assume a fixed package filename or use numbers in filenames to determine compatibility. The commands below prompt you to enter the path to the file you actually downloaded.
-
Identify your system
Run
cat /etc/os-releaseanduname -mto note your distribution and CPU architecture. Don't use the desktop theme to identify your system. -
Choose a file
Open the Linux section of the all-platform downloads page and select the matching DEB, RPM, or AppImage file. Wait for the browser to finish downloading it before continuing.
-
Copy the path
Use the file manager's properties to find the file location, then get its full absolute path, including the filename. When prompted below, don't add quotation marks.
-
Follow the instructions for your package
Run the relevant commands in a Bash terminal. If an error occurs, read the terminal output before proceeding; don't try multiple package formats one after another to force an installation.
3. Debian and Ubuntu: Install DEB with apt
For a DEB package that matches your system, use apt to install the local file. Unlike a simple extraction, apt checks dependencies and attempts to retrieve any required packages from your configured software sources. Installation may require access to your distribution's repositories; having the package file locally doesn't mean the whole process can be completed offline.
read -r -p "Enter the absolute path to the DEB file: " pkg
dpkg-deb -f "$pkg" Package Architecture
sudo apt install "$pkg"
The first command checks the package name and architecture without installing it. Confirm that the output matches your expectations before running the installation command. The absolute path lets apt recognize the input as a local file. If you use a relative path, prefix it with ./ instead of entering just the filename.
- If dependency downloads fail, check your network connection, repository URLs, and package index. If needed, run
sudo apt updateand try again. - If the package architecture doesn't match, check the download page and
uname -magain. Don't bypass the check with force options. - If no installable candidate is available for a dependency, check whether your distribution meets the package requirements. Don't mix software sources from different distributions.
- After installation, launch Shadowrocket from the application menu. Don't use sudo to start the graphical interface.
To update later with a new local DEB file, install it with apt and let the package manager determine how to upgrade it. Installing a local DEB doesn't automatically configure an app update repository. Check your actual software source configuration rather than assuming one exists because installation succeeded.
4. Fedora: Install RPM with dnf
On systems that use dnf, check the RPM package information before installing it. dnf resolves dependencies against both the local package and the system's installed packages and enabled repositories. RPM files with the same extension may still have different runtime requirements if they're built for different distributions.
read -r -p "Enter the absolute path to the RPM file: " pkg
rpm -qp --queryformat '%{NAME}\n%{ARCH}\n' "$pkg"
sudo dnf install "$pkg"
Before the installation transaction starts, review the additions, upgrades, and removals listed by dnf. If the output shows a large number of unexpected system component changes, cancel the transaction and check the file and distribution requirements on the download page. Don't accept unexplained system-wide changes just to install one app.
DEB installation checks
- System information
cat /etc/os-release- Package information
dpkg-deb -f "$pkg" Package Architecture- Local installation
sudo apt install "$pkg"
apt handles the installation transaction and dependencies. The file must be compatible with your system.
RPM installation checks
- Machine architecture
uname -m- Package information
rpm -qpi "$pkg"- Local installation
sudo dnf install "$pkg"
These commands are for dnf systems. The RPM format alone doesn't guarantee compatibility across distributions.
5. AppImage: Grant Execute Permission and Run
AppImage typically doesn't require installation with apt or dnf. Save the file somewhere your user can access, grant it execute permission, then run it directly. Choose a permanent location before launching it so you don't move or delete the original file afterward. The commands below affect only the selected file; they don't change permissions recursively on a directory.
read -r -p "Enter the absolute path to the AppImage file: " pkg
chmod +x "$pkg"
"$pkg"
If double-clicking the file has no visible effect, run the last command in a terminal and keep the error text. A Permission denied message may mean the file lacks execute permission, or that its partition is mounted with the noexec option. Repeating chmod won't change a partition's mount restrictions.
- Run
ls -l "$pkg"to check permissions and confirm your user has the required read and execute permissions. - If you see
Exec format error, first check the CPU architecture and whether the file downloaded completely. This isn't a subscription connection error. - For FUSE-related errors, check your distribution's documentation for the required compatibility components. Package names vary by distribution, so don't copy installation commands from another system.
- If a shared library or runtime symbol is missing, save the complete error message and check the system compatibility requirements. Execute permission alone can't provide a missing runtime environment.
An AppImage usually won't appear in the package manager as an installed app like a local DEB or RPM, and you can't assume an application menu entry was created. Before updating, close the app and keep a copy of your configuration, then replace the file as described on the download page. The new file may need execute permission again.
6. First Launch: Check Installation and Routing Separately
If Shadowrocket opens, that only confirms the app launched; it doesn't mean the subscription is valid or traffic is being routed through a proxy. First confirm your existing service details, then check the server selection and connection status in Home. Manage configuration files in Config, and use Global Routing to choose the routing mode. When troubleshooting, change one setting at a time.
The comparison below covers Shadowrocket's own Global Routing settings, not performance differences between package formats. DEB, RPM, and AppImage are distribution formats, not indicators of connection speed.
Config
RecommendedRoutes connections according to the rules in your current configuration. Rules can specify a proxy, a direct connection, or another defined policy; unmatched traffic doesn't necessarily go direct by default. The final outcome also depends on the fallback rule.
Use when: You have a working configuration and need to route traffic by domain or IP rules.
Proxy
Sends connections handled by the client through the current proxy policy. This can temporarily rule out the effect of routing rules, but it won't fix incorrect server settings or guarantee that traffic not handled by the client uses the proxy.
Use when: Briefly checking whether the proxy connection and rule matching share the same issue.
Direct
Sends connections handled by the client directly. Being able to open a website in Direct mode doesn't prove that the proxy server works. Check the current routing mode before testing the proxy.
Use when: Checking whether the target is reachable over your regular network.
For example, these two lines send example.com and its subdomains direct, while FINAL sends all other connections to PROXY. PROXY must correspond to a policy available in your current configuration. This snippet illustrates rule order; it isn't a complete file to replace your existing configuration.
DOMAIN-SUFFIX,example.com,DIRECT
FINAL,PROXY
If Connectivity Test in Home returns a result but browser access still doesn't work as expected, check whether the browser has separate proxy settings, whether the system proxy points to the actual listening address, and whether Global Routing matches your test. Don't rely on common port numbers found online; use the port configured on your device.
7. Common Installation and Launch Issues
apt says it can't find the file. Is the package corrupted?
First check that you entered the full local path. Run ls -l "$pkg" to confirm the file exists and isn't a temporary browser download. Prefix relative paths with ./; absolute paths start with /. A file path isn't a package name from a software repository.
I ran chmod on the AppImage. Why won't it open?
Run the file in a terminal and read the error. Check execute permissions, a noexec mount, architecture, FUSE, and runtime libraries in turn. Don't use chmod 777 to grant excessive permissions, and don't assume every launch failure is a network issue.
Do I need to install AppImage after installing the DEB package?
Once the app is installed and running, you don't need to install another package format to import a subscription. Multiple copies make it harder to identify launchers and configuration locations. Before switching formats, close the app, back up your configuration, and note how the original was installed.
The app opens, but subscription updates fail. Should I reinstall it?
First check your existing subscription URL, its validity, and your current network. Then check the routing conditions required to access that URL. A subscription is configuration data; reinstalling the app won't change the server address or authorization status. Don't share the full subscription URL when troubleshooting—it may contain an access token.
When documenting an issue, include the distribution name, uname -m output, package format, commands run, and the complete error text. This helps distinguish a failed installation transaction from an incompatible runtime environment or a connection configuration issue. Remove subscription tokens, server passwords, and other credentials before sharing.
Download Shadowrocket and continue setup
The iPhone and iPad app costs $2.99 as a one-time App Store purchase; check the App Store listing for system requirements. The Mac (Apple silicon and Intel), Windows, Android, and Linux versions are free. Choose the file for your system on the downloads page, then follow the guide to import your existing subscription and check routing settings.