This guide is for users preparing to install Shadowrocket on a Linux desktop. First, identify your distribution and processor architecture, then choose a DEB, RPM, or AppImage from the download page. Install it with your package manager or make the AppImage executable. Finally, distinguish installation errors from desktop launch failures and connection or configuration issues so you can troubleshoot each separately.
Check your distribution, architecture, and package format
Get the Shadowrocket Linux package from this site's download page. Choose a format based on your distribution and an architecture based on your device and system environment. The same file extension does not guarantee that a package supports your processor. An AppImage is not necessarily compatible with every architecture, either.
Run these two commands in a desktop terminal. The first displays your distribution details; check ID, ID_LIKE, and PRETTY_NAME. The second shows the machine architecture reported by the kernel. Common values such as x86_64 and aarch64 represent different architectures. Check the download page for the architectures actually supported.
cat /etc/os-release
uname -m| System environment | Formats to check first | How to install |
|---|---|---|
| Debian, Ubuntu, and compatible distributions | deb | Use apt to install the local package and handle dependencies available from your configured repositories. |
| Fedora and compatible distributions that use dnf | rpm | Use dnf to install the local package, then review the transaction for dependency changes. |
| Other desktop distributions | AppImage | Check the architecture and runtime environment first, then add execute permission. |
Install a DEB package with apt
On Debian or Ubuntu desktops, use apt to install DEB packages. A software installer opened by double-clicking a DEB can also handle local packages, but the terminal preserves the full error output, making it easier to identify missing dependencies, an incompatible architecture, or insufficient permissions.
-
Check your system
Run
cat /etc/os-releaseanduname -m. Confirm that your system uses apt and note the architecture. -
Get the package
Open the Linux section of the download page and choose the appropriate DEB package. Keep the downloaded filename as is; don't change its extension manually.
-
Copy the file path
Find the file in your file manager and copy its full path. After running the command below, paste the path at the terminal prompt. Don't add quotation marks around your input.
-
Install the package
Review the installation and dependency changes listed by apt, then confirm to continue. Once installation succeeds, launch Shadowrocket from your desktop's app list. Don't use sudo to launch a graphical app.
read -r -p 'Paste the full path to the DEB file: ' pkg
pkg=$(realpath -- "$pkg")
sudo apt install "$pkg"Here, pkg is a terminal variable that stores the file path you enter. The double quotes in the command protect paths containing spaces. realpath converts the path to an absolute path, preventing apt from treating a bare filename as a package name from a repository. Before running the command, make sure the path points to an existing DEB file.
- If apt reports unmet dependencies, check which dependencies are missing and what they require, then confirm that your distribution is supported.
sudo apt updaterefreshes the indexes for configured repositories; it won't make an incompatible package compatible. - If the architecture doesn't match, check
uname -magainst the architecture listed on the download page. Don't bypass the check with force options. - If a previous attempt left dependency changes unresolved, review the changes proposed by
sudo apt --fix-broken install. Continue only if they won't remove software you need.
Install an RPM package with dnf
On systems that use dnf, use it to install local RPM packages. It usually handles dependencies more conveniently than calling the lower-level rpm installer directly. RPM is a package format, not a guarantee of compatibility: distributions may differ in their repositories, system libraries, and packaging conventions.
read -r -p 'Paste the full path to the RPM file: ' pkg
pkg=$(realpath -- "$pkg")
sudo dnf install "$pkg"This command passes the local package to dnf, which uses your system's repositories to find available dependencies. When the transaction summary appears, review each package to be installed, upgraded, or removed. If it proposes many replacements or removals unrelated to the package, cancel and check whether the package matches your system.
Check the DEB package path
- Installer
apt install- Input
- Absolute path to the local DEB package
- Dependency source
- Currently configured repositories
- Success criteria
- The installation transaction completes without errors
If the installer reports an error, resolve the package or dependency issue before troubleshooting connectivity.
Check the RPM package path
- Installer
dnf install- Input
- Absolute path to the local RPM package
- Dependency source
- Currently enabled repositories
- Stop if
- The architecture is incompatible or dependencies cannot be satisfied
Don't skip dependency checks to make a failed transaction appear successful.
If the terminal reports dnf: command not found, first check which package manager your system actually uses. Not every distribution that supports RPM uses dnf. Don't install another package manager just to copy a command from this guide. Check your distribution's documentation and the download page's supported systems, then choose the appropriate installation method.
Run an AppImage: add execute permission and check the output
An AppImage usually runs as a single executable file and isn't registered as a regular system package through apt or dnf. Move it to a fixed directory owned by your user, then add execute permission. For the first launch, run it from a terminal in your desktop session so you can see any errors. Don't run the entire graphical app with sudo.
read -r -p 'Paste the full path to the AppImage file: ' app
app=$(realpath -- "$app")
chmod u+x -- "$app"
"$app"chmod u+x adds execute permission for the file owner. The common form chmod +x also adds execute permission, but this guide explicitly changes only the owner's execute bit. Double quotes around the variable ensure a path containing spaces is passed as a single argument. Execute permission doesn't change the architecture or provide missing system libraries.
- If you see
Permission denied, usels -l -- "$app"to check the execute bit and see whether the file is on a mount that prohibits execution. Even with the execute bit set, thenoexecmount option can prevent the file from running. - If you see
Exec format error, check the architecture and file format. Don't keep changing permissions; they aren't the likely cause of this error. - If a FUSE library is missing, install a compatible component according to your distribution's documentation. Package names can vary, so don't copy a package name from another system.
- If the display server can't be reached, make sure you're running the app in a logged-in graphical desktop session. A regular SSH terminal or an environment without a display server isn't equivalent to a desktop session.
After the first launch: distinguish a successful install from a working connection
If the Shadowrocket window opens, the app has reached the desktop launch stage. This doesn't mean you've imported your existing service or that system traffic is being handled as expected. Use the installer output to troubleshoot installation issues and the app's configuration and connection status to troubleshoot network issues. Check them separately.
In Home, check the current service configuration against the details you already have, including the address, port, protocol, and authentication fields. Don't guess a port based on the protocol name. For example, if your service details specify port 443, enter that value; don't change it just because you use a different protocol. Don't include a full link containing access credentials in public logs or screenshots.
Config
RecommendedGlobal Routing uses the rules in the currently selected configuration. First, check in Config that a configuration file is selected. Connections that don't match earlier rules are handled by the policy specified in FINAL; they aren't necessarily sent direct.
Use when: You have a verified configuration file and need traffic routed by destination.
Proxy
Routes connections handled by the app through a proxy. This can help determine whether rule-based routing is related to an issue. It doesn't mean that every process or protocol on the operating system is being handled.
Use when: You have a working service and want to narrow down whether rules are causing a problem.
Direct
Attempts a direct connection to the destination. If the destination requires your existing proxy service, Direct can't tell you whether that service is working.
Use when: Checking basic network connectivity and direct access.
Use Scene in Global Routing with a scene you've already configured; it isn't the default choice for troubleshooting a new installation. On Demand in Settings triggers connections under specified conditions, but it won't resolve missing dependencies or grant execute permission. First confirm the connection manually, then set up automation. Available options vary by platform.
Installation troubleshooting and updates
I downloaded a DEB, but my system says it's unsupported. Can I change the extension to RPM?
No. The extension doesn't determine the package's internal format. Run cat /etc/os-release to identify your system, then choose the matching format from the download page. Don't try to install it by renaming the file or bypassing package manager checks.
I've run chmod +x on an AppImage. Why won't it open when I double-click it?
Run the file from a terminal in your graphical desktop and check the first error message. For a permissions error, check the execute bit and mount options. For an architecture or missing-library error, troubleshoot that specific issue. Nothing appearing after a double-click isn't enough to identify the cause.
Installation succeeded, but why can't I find the app in the menu?
Close and reopen the desktop app search first. Whether a DEB or RPM package appears in the menu depends on whether it includes a desktop launcher. An AppImage may not register a menu entry automatically. Don't guess the executable's command name or reinstall the app in another format just because it isn't listed.
Do I need to delete all the old files before updating?
Save your existing configuration first. You can update a DEB or RPM package with its package manager if the package identity and upgrade path are compatible. If you see a conflict, stop and read the explanation. For an AppImage, quit the app before replacing the file, then check its execute permission and shortcut path.
When you finish troubleshooting, keep a record of your distribution, architecture, package format, command, and full error message. These details are more useful for diagnosing the issue than saying it won't open. Before sharing logs, remove subscription credentials, passwords, and other sensitive information. If the app opens but you can't connect, troubleshoot the connection and configuration instead of rerunning installation commands.