At a glance

This guide covers distro and architecture checks before installing Shadowrocket on Linux, commands for installing local DEB and RPM packages, AppImage permissions, and configuration checks after first launch. It’s for users who already have connection details or a subscription from their provider and want to install the client on a Linux desktop. First make sure the system and package match, then resolve dependencies. Launching the app and establishing a connection are separate checks.

1. Check your distro, architecture, and package format

Choose a Linux package for Shadowrocket from the downloads page for all platforms. DEB, RPM, and AppImage are different distribution formats; they do not indicate different proxy protocols or service plans. Don’t identify your distro by desktop appearance alone: GNOME and KDE are desktop environments and don’t determine whether you should use apt or dnf.

Run these two read-only commands in a terminal first. The first checks the system identifier; the second reports the processor architecture. If you share the output for troubleshooting, the distro name, architecture, and error text are usually enough—there’s no need to share account details.

cat /etc/os-release
uname -m

Identify your system

NAME / ID
Read /etc/os-release to confirm the actual distro name.
ID_LIKE
Use this as a secondary clue to the distro family; it does not replace the package-management guidance for your distro.
uname -m
x86_64 and aarch64 are different architectures; the package must match your system.

Check which architectures are actually available on the downloads page. Switching package formats won’t fix an architecture mismatch.

Choose a package format

Debian / Ubuntu
Prefer DEB. Use apt to install the local package and resolve dependencies.
Fedora-based distros
Prefer RPM. Use dnf to install the local package and resolve dependencies.
Other distros
Check AppImage compatibility notes, and verify the architecture and runtime requirements.

AppImage still depends on system libraries, the desktop environment, and runtime requirements; it isn’t compatible with every Linux system.

If the system is running in a container, on a headless server, or in a remote terminal, a successful installation doesn’t mean it can run desktop apps. First confirm that the current session can launch graphical programs, then continue with the client. This guide covers Linux desktops, not server service deployment.

2. Debian / Ubuntu: Install a local DEB with apt

On the downloads page, choose the DEB package that matches your architecture and note its full file path. Run the commands below line by line in Bash. When prompted, enter the actual absolute path—for example, copy it from your file manager and paste it. Don’t add extra quotation marks around your input. The variable in the command stores the actual file path, so there’s no need to guess the package filename.

read -r -p "Enter the absolute path to the DEB file: " deb_path
dpkg-deb -f "$deb_path" Package Architecture
sudo apt update
sudo apt install "$deb_path"

dpkg-deb -f reads package metadata without installing the package. Common architecture mappings are: if your system reports x86_64, look for the package’s amd64 marker; if it reports aarch64, look for arm64. In either case, the package must match what’s available on the downloads page. If the fields clearly don’t match, stop and choose a different package.

Don’t assume the app is ready to use if dpkg -i reports dependency errors. dpkg tracks package installation status, but unlike apt, it doesn’t resolve and fetch dependencies from software sources. When installation finishes, make sure the terminal reports no unconfigured packages, then launch Shadowrocket from your desktop app list.

3. Fedora-based distros: Install a local RPM with dnf

Check the architecture before installing an RPM; the file extension alone isn’t enough. Fedora-based distros typically use dnf to install local RPM packages and handle dependencies. Other RPM-based distros may use different package managers and dependency names. Don’t copy Fedora software-source settings just because the package extension is the same.

read -r -p "Enter the absolute path to the RPM file: " rpm_path
rpm -qp --queryformat '%{NAME} %{ARCH}\n' "$rpm_path"
sudo dnf install "$rpm_path"

The query command displays only the package name and architecture, making it easy to verify the download. dnf’s transaction confirmation screen lists what will be installed and where dependencies come from. Continue only if the package came from this site’s downloads page, the architecture matches, and the dependency plan looks reasonable. If there’s a package conflict, keep the error output; don’t hide the problem with options that skip dependencies or force an overwrite.

  1. If you see No such file or directory, first check that you entered the file’s actual path, not the name displayed in the browser’s download list.
  2. If dependencies can’t be met, check your distro’s software sources and compatibility requirements. Don’t copy system libraries from another distro at random.
  3. After installation, launch the graphical app as a regular user. Using sudo to install it doesn’t mean you need sudo to run it.

4. AppImage: Make it executable and launch from a terminal

AppImage packages usually aren’t registered as installed through apt or dnf. Move the file to a location you can write to and keep long term, then make it executable. If it stays in the browser’s temporary directory, clearing downloaded files may prevent it from launching again. Moving the file may also mean updating the path in any existing desktop shortcuts.

read -r -p "Enter the absolute path to the AppImage file: " app_path
chmod u+x "$app_path"
"$app_path"

chmod u+x adds execute permission for the file owner only. The last command runs the file directly, keeping any startup errors visible in the terminal—useful if double-clicking doesn’t open a window. Don’t launch the entire desktop client with sudo or treat broader file permissions as a general fix.

Making an AppImage executable doesn’t turn it into a system service or mean it supports automatic updates or desktop menu integration. To update, check the downloads page for instructions, exit any running instance, then replace the file as described for that package.

5. First launch: Separate installation issues from connection issues

If the window opens, some local runtime checks have passed. If websites still won’t load, investigate your connection details, routing mode, and system network settings instead of immediately reinstalling a different package. The steps below assume you already have connection details and a subscription from your provider. Subscription URLs may contain credentials, so redact the full link before sharing screenshots or logs.

  1. Check that it launches

    Launch Shadowrocket from your app list or run the AppImage, then confirm the window stays open. If it exits immediately, reproduce the issue in a terminal and record the error before troubleshooting subscriptions.

  2. Import your details

    Go to Home → + → Type → Subscribe, enter your own subscription URL, and save it. This shows the URL format: https://example.com/sub?token=xxxx. It’s an example only and won’t connect. The exact location may vary in the current Linux build.

  3. Check the configuration

    After updating the subscription, make sure the expected items appear in the list. Then open Config to check the current configuration and its policy references. A failed subscription fetch and an unavailable connection entry are different problems; keep their error details separate.

  4. Check the routing mode

    Go to Home → Global Routing and check the current selection. To test configuration rules, use Config and confirm that the referenced policy names are valid. Don’t use Direct mode to judge whether a proxy connection is working.

Home, Config, and Global Routing refer to the relevant features; their entry points may differ between platform builds. Don’t repeatedly reinstall the Linux package to find a menu from a mobile version. System proxy settings and in-app routing are also separate layers: only connections handled by the client are affected by its routing mode. The client’s toggle doesn’t prove that it has taken over all device traffic.

6. Choose a Global Routing mode after installation

The package format doesn’t change how rules match. After installation, use Global Routing to help distinguish a connection problem from rules that aren’t matching. The options below compare routing modes within Shadowrocket only. Before testing, make sure you’ve imported your own valid connection details.

Config

Recommended

Routes connections according to the active configuration’s rules and policies. Rules don’t necessarily send everything through a proxy; the result depends on the matching rule, its policy target, and the configuration’s fallback behavior.

Best for: Everyday use with a verified configuration that should route traffic according to its rules.

Proxy

Sends connections handled by the client to the selected proxy policy. This can reduce rule matching as a factor when troubleshooting, but it doesn’t mean the operating system’s entire traffic flow is handled by the client.

Best for: Briefly comparing a selected connection with configuration-based routing.

Direct

Handles connections within the client’s scope as direct connections. It can’t fix DNS, the system firewall, or the physical network, and it can’t confirm that a proxy connection works.

Best for: Checking local network reachability as a comparison, without the proxy path.

If websites load in Proxy mode but fail under Config, check rule order and policy references in Config instead of reinstalling the DEB or RPM. DOMAIN-SUFFIX matches domain suffixes, IP-CIDR matches address ranges, GEOIP matches IP geolocation data, and FINAL provides a fallback. The result still depends on the actual configuration and connection details.

7. Installation and update FAQs

The DEB downloaded successfully. Why does apt say it can’t find the package?

First check that you’re passing apt a local file path. Use the full absolute path, or go to the directory containing the file and use a relative path starting with ./. If you enter only the filename, apt may treat it as a package name from a software source. Also make sure the browser has finished downloading the file.

Nothing happens when I double-click an AppImage. Should I download it again?

First run the permission and launch commands in this guide from a terminal to identify whether the issue is permissions, architecture, or the runtime environment. If the error mentions FUSE or GLIBC, address the corresponding environment requirement. Downloading the same file again usually won’t change system dependencies.

Can I switch from DEB to AppImage when upgrading?

Use the app’s export feature to back up your configuration, then exit the old instance. Configuration locations, launch methods, and desktop integration may differ between package formats, so don’t assume they’ll migrate automatically. Check that the new instance works before deciding whether to remove the old package, and avoid accidentally running both instances.

Installation succeeded, but the subscription still won’t update. Why?

Check the full subscription URL, network reachability, and any error returned by your provider. Don’t expose the token in a terminal or public logs. If the app launches and can read local configuration, investigate the subscription fetch path first instead of blaming the package format for a network timeout.

When reporting an installation issue, include your distro name, the output of uname -m, the package format you chose, the commands you ran, and the full error text. Don’t guess the app’s installation directory or executable filename. Never attach configuration containing a password, PrivateKey, or subscription token.