At a glance

Before installing Shadowrocket for Linux, check your distribution and processor architecture, then choose a .deb, .rpm, or AppImage from this site’s download page. This guide covers local installation commands, AppImage permissions, first-launch checks, and how to tell installation problems from connection configuration issues. It’s for users with a desktop Linux environment who plan to import a configuration from a service they already use.

Check your distribution, architecture, and environment first

Package format and processor architecture are separate requirements. The .deb format is for Debian-based systems such as Debian and Ubuntu. This guide uses rpm with Fedora’s dnf workflow. An AppImage may suit other desktop distributions, but it still depends on processor architecture, system libraries, and the runtime environment—it is not guaranteed to work on every Linux system.

Open Terminal and run these two commands. The first prints your distribution ID; the second shows the machine architecture reported by the kernel. Match the result to the architectures actually listed on the download page. Don’t rely on your computer’s brand, and don’t rename a file to make it look like another package format.

cat /etc/os-release
uname -m
3 types
Linux package formats: .deb / .rpm / AppImage
2 checks
Check the distribution family and processor architecture first
1 check
Check AppImage execute permissions before launch

Choose an installation method for your system

Go to the Linux section of the app download page and choose a file that matches your system. This guide doesn’t specify package filenames, so an outdated name won’t be mistaken for the current download. After downloading, check your browser’s download history for the save location. Use that exact file path in the commands below.

How to choose: system package manager or standalone file

Debian / Ubuntu / Fedora
  • Debian / Ubuntu: choose a .deb and install the local file with apt.
  • Fedora: choose an .rpm and install the local file with dnf.
  • The package manager records the installation and attempts to resolve dependencies from your enabled repositories.
Other desktop distributions
  • First check whether the download page offers an AppImage for your architecture.
  • Make the file executable, then launch it as a regular user.
  • Keep it in a location where you have write and execute access. If you encounter dependency errors, troubleshoot them for your distribution.

Use the system package manager when a compatible package is available. For an AppImage, check system compatibility and execute permissions separately.

Test one installation method at a time. If you keep both a package-manager installation and an AppImage, the desktop menu entry and the file launched from Terminal may point to different copies. Note the actual launch path when troubleshooting, so you don’t change one copy while continuing to open another.

Install commands: use the actual path to your downloaded file

These commands are written for Bash. Each set prompts you for the file’s full path. Paste the path as-is; don’t add extra quotes. The double quotes in the commands protect paths containing spaces, and realpath -e checks that the file exists. If you enter the wrong path, stop—don’t run the installation command.

Debian / Ubuntu: install a .deb with apt

read -r -p 'Enter the full path to the deb file: ' pkg
pkg=$(realpath -e -- "$pkg") && sudo apt install "$pkg"

Enter the absolute path to the local file, not a package name from a repository. apt will show the package, dependencies, and disk space required; review these before confirming. Dependency downloads require access to your configured repositories. If installation fails, check the dependency name and repository error shown in Terminal instead of repeatedly double-clicking the package.

  • If you see a file-not-found message, check your browser’s download history and confirm the path, capitalization, and that the download has finished.
  • If dependencies can’t be satisfied, check your distribution version, architecture, and repository configuration. If needed, run sudo apt update and try again, keeping the original error message.
  • If the package manager is locked, wait for system updates to finish. Don’t delete the lock file.

Fedora: install an .rpm with dnf

read -r -p 'Enter the full path to the rpm file: ' pkg
pkg=$(realpath -e -- "$pkg") && sudo dnf install "$pkg"

Use dnf rather than a low-level installation command so it can also handle dependencies available from system repositories. rpm is a file format; distributions that use it don’t necessarily have the same dependency versions. Don’t assume Fedora compatibility applies to other distributions.

  • Review the changes listed in the installation transaction. Cancel if it unexpectedly proposes removing many packages.
  • If the architecture doesn’t match or a system library is missing, return to the download page and check which systems the package supports.
  • Don’t force installation by ignoring dependencies; this can leave you with an application that won’t launch.

AppImage: make it executable, then run it

read -r -p 'Enter the full path to the AppImage file: ' app
if app=$(realpath -e -- "$app"); then
  chmod u+x -- "$app" && "$app"
fi

chmod u+x adds execute permission for the file owner only; there’s no need to make the file writable by everyone. Don’t use sudo to run the AppImage. For the first launch, run it from Terminal so you can see errors about missing libraries, FUSE, or a graphical session even if no window appears.

First launch: verify the app, then import your configuration

Successful installation and a working connection are separate things. First confirm that the app opens, then import a configuration you already have, and finally check the connection. The steps below refer to the Home, Config, and Settings sections. Button layouts may differ by platform, so confirm the interface labels instead of guessing from icon positions.

  1. Confirm that the app launches

    After installing a system package, open Shadowrocket from your desktop’s application menu. For an AppImage, run it using the full path you just checked. If no window appears, read the Terminal output before changing network settings.

  2. Import an existing configuration

    Go to Home → Add → Type → Subscribe, enter your own subscription URL, save it, and update. A subscription URL may contain access credentials; don’t post the full URL in public logs or screenshots.

  3. Check your rules

    Go to Config and confirm which configuration is active, then check the Global Routing selection. Installing the app doesn’t guarantee that your existing rules, policy names, and server parameters are compatible with one another.

  4. Test the connection

    In Home, select an available connection from your existing configuration and turn it on. Check the connection status and browser access separately. If a permission prompt appears, check which app is requesting access before following the system prompt.

If the app opens normally but won’t connect, check the address, port, authentication details, and transport parameters instead of repeatedly changing the installation package. Shadowsocks, VMess, VLESS, Trojan, Hysteria2, and WireGuard use different parameter formats; copying only a server address is not enough to finish the configuration. This site does not provide, sell, or recommend nodes or subscriptions.

Distinguish Global Routing settings from installation issues

Being able to open a website in your browser doesn’t by itself prove that traffic followed the intended policy. An enabled connection toggle also doesn’t mean every connection takes the same route. Check Global Routing first, then review the rules in your current configuration. The comparisons below describe the purpose of Shadowrocket’s own settings only.

Config

Recommended

Choose how to handle connections according to the rules in your current configuration. Rule order and policy references determine the result; Config shouldn’t be reduced to a fixed split between direct and proxied traffic.

Use for: everyday use of an existing rules configuration and traffic-routing checks.

Proxy

Handles connections routed through the app in proxy mode, which can help you compare results with Config. It doesn’t mean that every connection from every process on your system will necessarily be routed through the app.

Use for: temporarily checking whether an issue is related to rule matching.

Direct

Handles connections routed through the app in direct mode. While this mode is selected, a working webpage doesn’t prove that your proxy settings are correct.

Use for: comparing results with direct access on your local network.

If Global Routing is set to Scene, first check which scene is active and what conditions it uses, then compare it with the modes above. Settings → On Demand controls connections triggered by conditions; it doesn’t install dependencies or fix AppImage execute permissions.

Common errors: troubleshoot the symptom instead of reinstalling

AppImage does nothing when double-clicked. What should I check?

Run the file from Terminal first and read the error. If you see Permission denied, check whether chmod u+x succeeded. If execute permission is already set, check whether the filesystem is mounted with noexec. You can move the file to an executable location in your home directory and try again; don’t change security settings for the entire disk.

The file is in the directory. Why does the system say it can’t find it?

Linux doesn’t search the current directory for executables by default. Use the file’s absolute path or add ./ before its name. If you still get No such file or directory with the absolute path, check whether the error comes from the program loader or a missing runtime library instead of repeatedly renaming the file.

Getting “Exec format error.” Should I switch to an .rpm?

Run uname -m to check your architecture, and verify the downloaded file type. This error may indicate an architecture mismatch; changing the file extension won’t fix it. If the download is incomplete or the file isn’t actually an application, check your browser’s download history. Don’t assume the cause from one error alone.

The app opens, but webpages fail after I turn on the connection. What should I do?

Keep the working installation in place and check the connection parameters in Home, Global Routing, and Config. Confirm that your system clock is accurate, then test server connectivity and rule results separately. Don’t use uninstalling and reinstalling as a substitute for checking the parameters.

Updates and cleanup: keep your configuration recoverable

Before updating, save your current configuration and any connection parameters you need, then check the backup’s actual contents. Configurations may contain subscription URLs, passwords, or keys; store them somewhere only you can access. An app screenshot is not a complete backup, and you shouldn’t assume that uninstalling will either preserve or delete your configuration.

Record your distribution, architecture, installation method, launch method, and the first error shown in Terminal. This is usually more useful than simply saying “it won’t open.” If installation is complete, troubleshoot the actual error. Avoid changing repositories, file permissions, and connection settings all at once, so you can tell which change made a difference.