Shadowrocket for Linux: Install the DEB, RPM, or AppImage

Choose the right package for your Linux distro: install DEB with apt, RPM with dnf, or make the AppImage executable. Includes fixes for common first-launch errors.

At a glance

This guide is for users installing Shadowrocket on a Linux desktop who already have a service provider and subscription. Check your distro and CPU architecture first, then choose a DEB, RPM, or AppImage. After installation, verify that the app launches, the subscription imports, and requests connect—so you can distinguish installation issues from configuration problems.

1. Check your distro, architecture, and package format

DEB, RPM, and AppImage are different ways to distribute Linux software, not different proxy protocols. Choose a package based on your distro’s package manager, then check the architecture and system requirements listed on the download page. Renaming a file from .rpm to .deb won’t convert its format or fix an architecture mismatch.

Open a terminal and run these commands. /etc/os-release identifies your distro, while uname -m reports your architecture. Check both separately; a desktop’s appearance isn’t enough to identify them.

cat /etc/os-release
uname -m
FormatCommonly used onHow to install or runKeep in mind
debDebian, Ubuntu, and derivatives that use aptInstall the local file with aptRegisters the package with the package manager, which resolves dependencies from configured repositories.
rpmFedora and distros that use dnfInstall the local file with dnfUsing RPM format doesn’t mean every distro uses dnf.
AppImageLinux desktops that meet the file’s runtime requirementsMake executable, then runStill depends on CPU architecture, system libraries, FUSE, and mount options.

For example, x86_64 often corresponds to x64 or amd64 on the download page, while aarch64 often corresponds to arm64. These are architecture naming conventions, not a guarantee that every combination is available. Check the all-platform download page for available files. Repeatedly adding execute permissions won’t fix an architecture mismatch.

2. Download the file and note its details

Select Linux on the download page, then choose a format for your distro. Get files through this site’s download page; there’s no need to construct a package URL yourself. Note the download folder and the exact filename—you’ll need them to install the package, troubleshoot issues, and check package details.

  1. Check your system

    Open a terminal, run the two commands from the previous section, and note your distro and architecture. A remote terminal may be connected to a different system than your desktop, so confirm which machine you’re working on.

  2. Choose a format

    Go to the Linux section of the all-platform download page. Choose DEB for systems using apt and RPM for systems using dnf. If you’re considering AppImage, check its runtime requirements first.

  3. Note the file path

    In your file manager, view the file’s properties and copy its full path. When a terminal prompt asks for the path below, enter it without extra quotation marks; don’t use an unexpanded tilde in place of your home directory.

  4. Check the download

    Confirm the file came from this site’s download page and finished downloading. If the filename still has a temporary browser download suffix, wait for the download to finish before installing. Don’t remove the suffix manually and try to run the file.

3. Install the DEB or RPM, or run the AppImage

Run the commands below in Bash, using only the set that matches your chosen format. Each command prompts for the actual file path, so there’s no assumed package filename. Double quotes around the variable preserve spaces in the path. Close Shadowrocket before installing.

DEB: Let apt handle the local package and dependencies

Run these commands on an apt-based system such as Debian or Ubuntu. After entering the file’s absolute path, review apt’s proposed installation, upgrade, or removal actions before confirming. Don’t use a force-install option just to bypass a dependency error.

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

dpkg-deb outputs the package name and architecture, which you can use to check the file you selected. If apt reports missing dependencies, first check that your system’s repositories are available. To refresh the package index, run sudo apt update, then try again. Refreshing the index doesn’t upgrade the whole system or automatically resolve incompatible distro requirements.

RPM: Install a local package on a dnf-based system

Run this set on Fedora and other systems that use dnf. It checks the package details, then lets dnf resolve dependencies. If your system uses RPM format but not dnf, use its own package manager instead of switching tools just to copy this command.

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

If you see nothing provides, check the dependency name that follows and verify your system’s requirements and enabled repositories. Don’t force the installation by ignoring dependencies; a registered package doesn’t guarantee that the libraries needed to run it are available.

AppImage: Make it executable, then run it

Put the file somewhere your regular user can access and where it won’t be routinely cleaned up, then run these commands. AppImage isn’t registered with apt or dnf, so it won’t automatically appear in the package manager’s update or uninstall options when first launched.

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

4. After the first launch, check configuration and connectivity separately

A window opening only confirms that the app launched; it doesn’t mean your subscription, server, or routing rules are configured. Check the app in this order: use Home to review the connection and servers, Config to confirm the active configuration, and Settings to review relevant options. If the system asks for network access, read the prompt before approving it.

In the app

Home
Check the imported servers and the one currently selected.
Config
Confirm which configuration and Rule section are enabled.
Global Routing
Check whether the current mode is Config, Proxy, or Direct.
Connectivity Test
Test the selected server, then verify an actual request.

Change one setting at a time and note its previous state so you can assess the result.

On your system

CPU architecture
Compare the output of uname -m with the architecture listed on the download page.
System clock
Check the time zone and date; significant errors can affect TLS verification.
Network access
First confirm that your regular connection works, including any network sign-in page.
Server port
Use the details from your provider; don’t assume every protocol uses port 443.

System internet access and proxy connectivity are separate checks; one doesn’t confirm the other.

If you already have a subscription, tap “+” in the upper-right corner of Home to open the add screen. Set Type to Subscribe, enter the subscription URL from your provider, and save. Then update the subscription and confirm that servers appear on Home. A subscription update usually refreshes server details; it shouldn’t be assumed to replace all routing rules in Config.

When adding a server manually, don’t mix fields for Shadowsocks, VMess, VLESS, Trojan, Hysteria2, and WireGuard. Enter the protocol, address, port, and authentication details exactly as provided by your service provider. A subscription URL isn’t a server address for any one protocol. Before sharing troubleshooting details, hide subscription tokens, passwords, and Private Key values.

5. Use Global Routing to separate installation issues from routing issues

If some sites work and others don’t after installation, check Global Routing before reinstalling. The options below describe how Shadowrocket handles traffic; their scope depends on which traffic reaches the app. Proxy doesn’t necessarily capture every process on the system.

Config

Recommended

Handle requests according to the active configuration. Check the order and policies in the Rule section, and see which rule the destination matches. This is a suitable everyday mode once your rules are configured correctly.

Best for: everyday routing by domain and IP address.

Proxy

Handle requests that reach the app in proxy mode. This can temporarily help rule out the effect of routing rules. If the behavior changes after switching modes, investigate the configuration rather than assuming the system installation is broken.

Best for: briefly troubleshooting rules and policy selection.

Direct

Handle requests as direct connections, without forwarding them through a proxy server. Use this to check the underlying network. If a destination requires a proxy, failure in this mode doesn’t show that the server is unavailable.

Best for: comparing direct network access with proxy connectivity.

In Config, DOMAIN-SUFFIX matches domain suffixes, IP-CIDR matches IP address ranges, GEOIP matches by IP geolocation, and FINAL provides the final fallback. Rules are generally checked from top to bottom. If an earlier rule already matches a destination, changing a later rule won’t affect that request. Back up the current configuration before editing, and restore temporary diagnostic settings after testing.

6. Common first-launch errors and how to troubleshoot them

When troubleshooting, keep the full error message and the steps that triggered it—not just “it won’t open.” The issues below are common categories for installing and running Linux apps, but won’t occur on every distro. Check file execution and dependencies first, then app configuration, and finally the specific request.

AppImage says “Permission denied” even though the download is complete. What should I do?

First run chmod u+x "$pkg" on the actual file, then launch it from the same terminal. If it still fails, run findmnt -T "$pkg" -o TARGET,OPTIONS to check whether its filesystem has the noexec option. If it does, move the file to a user directory where execution is allowed; don’t change system mount settings.

I get “Exec format error.” Is this a permissions problem?

First check the file format or architecture; adding permissions usually won’t help. Compare uname -m, the architecture listed on the download page, and the output of file "$pkg". If file reports an HTML document, you may have downloaded an error page. Return to the download page and get the correct file.

AppImage reports that libfuse.so.2 is missing. What should I install?

Note the full error, then use your distro’s package search tool to find the FUSE-compatible runtime library that provides the file. Package names can vary by distro and release; don’t remove existing FUSE components. After installing the matching dependency, launch the app from a terminal as a regular user.

Clicking the icon does nothing. How can I find out why?

For an AppImage, run the file in a terminal using the path variable from above. For a DEB or RPM installation, check the actual launch command in your desktop launcher’s properties, then run it in a terminal. Note any output about missing libraries, the graphical session, or permissions. Don’t guess the executable’s name or disable security features without a reason.

The installation succeeded, but why does the subscription update still fail?

First confirm that regular network access works, the system clock is correct, and the subscription URL contains no extra spaces or line breaks. Then check that the subscription is active with your provider. If only one subscription fails, start by checking that URL and its network route; reinstalling the app usually won’t fix an expired token.

7. What to keep when updating or uninstalling

For updates, get a file with the same architecture and a suitable format from this site’s download page. DEB and RPM upgrades are generally handled by the corresponding package manager based on package metadata. For an AppImage, close the app, replace the file, and check its execute permission and any shortcut paths. Placing a file in your downloads folder won’t automatically update the app.

Choose a format that fits your system’s package management: use the appropriate DEB on apt-based systems and RPM on dnf-based systems. With AppImage, you’re responsible for checking the file location, permissions, and runtime dependencies. After installation, configure the subscription and connection using details from your service provider.

Download Shadowrocket