Install Shadowrocket on Linux: DEB, RPM, or AppImage

Choose a package for your distro: install DEB with apt on Debian/Ubuntu, RPM with dnf on Fedora, or make the AppImage executable on other distros.

At a glance

This guide is for users preparing to run Shadowrocket on a Linux desktop. Check your distribution and processor architecture, choose a DEB, RPM, or AppImage from our download page, and install it using the actual file path. Then check three things separately: app launch, subscription import, and traffic handling. The commands don't assume a specific package filename or local proxy port.

1. Check your distribution, architecture, and package format

DEB, RPM, and AppImage are software distribution formats, not proxy protocols. Choose a format based first on your system's package manager, then on the architectures listed on the download page. Debian and Ubuntu typically use DEB; Fedora uses RPM. On other distributions, check whether the AppImage's runtime requirements are met. Being able to extract a file doesn't mean a package built for another package-management system is suitable to install.

Run these two commands in a terminal. The first shows your distribution ID; the second shows your machine architecture. Don't identify your system by its desktop appearance alone: two computers with the same desktop environment may use different underlying distributions and package formats.

cat /etc/os-release
uname -m

System information

NAME / ID
Check your distribution in /etc/os-release.
ID_LIKE
Useful for identifying the distribution family, but not a substitute for compatibility information.
uname -m
x86_64 and aarch64 refer to different processor architectures.

Match both the package format and architecture; checking the file extension alone isn't enough.

Download and run

deb
Use apt to install the local file and handle dependencies.
rpm
On Fedora, use dnf to install the local file.
AppImage
Make the file executable, then run it as your desktop user.

Use the format and architecture actually offered on the download page. Don't convert package formats.

Get all installation files from the Linux section of the download guide. Packages are served through this site's /dl/ download mechanism. Don't construct download URLs from the commands in this guide. Shadowrocket is closed-source commercial software. The iPhone / iPad version is available on the App Store for a one-time payment of $2.99. The Mac (Apple silicon and Intel), Windows, Android, and Linux versions are free.

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

Run the following commands in Bash. The first prompts for the full path to the file you downloaded; enter it without adding quotes. The double quotes in the commands that follow protect paths containing spaces. Check the package metadata before installing. These commands inspect a local file; they won't search for software with the same name.

read -r -e -p "Enter the full path to the downloaded DEB file: " pkg
pkg="$(realpath -- "$pkg")"
dpkg-deb --field "$pkg" Package Architecture Depends
dpkg --print-architecture
sudo apt install "$pkg"

Providing the full path tells apt to install a local file. Without a path, a package name means apt will search the repositories. Compared with running dpkg -i alone, apt can handle dependencies in the same transaction when installing a local DEB. Your configured repositories must still be accessible and able to satisfy those dependencies.

If you see Unable to locate package, first check that you provided the actual file path. If dependencies can't be satisfied, check distribution compatibility and repository status. Don't bypass errors by forcing the installation to ignore dependencies, and don't treat an incomplete installation transaction as a successful install.

3. Fedora: Install a local RPM with dnf

Check the RPM package's architecture and metadata first. The commands below are for Fedora with dnf; other RPM-based distributions may use different package-management commands and dependency sets. The same file extension alone doesn't guarantee compatibility.

read -r -e -p "Enter the full path to the downloaded RPM file: " pkg
pkg="$(realpath -- "$pkg")"
rpm -qpi "$pkg"
rpm -qp --requires "$pkg"
uname -m
sudo dnf install "$pkg"

rpm -qpi displays information about a package file that isn't installed; rpm -qp --requires lists its required capabilities or dependencies. When installing with dnf, review the transaction summary before confirming. Downloading a local package doesn't mean all its dependencies have been downloaded; resolving them may still require access to your configured repositories.

4. AppImage: Making a file executable doesn't install it system-wide

An AppImage is usually kept as a single executable file; apt and dnf don't register it as a regular package. Move the file to a location where you intend to keep it, then make it executable. If you launch it from a temporary download folder, cleaning up that folder later will break the original launch path.

read -r -e -p "Enter the full path to the downloaded AppImage file: " app
app="$(realpath -- "$app")"
file -- "$app"
chmod u+x -- "$app"
"$app"

chmod u+x adds execute permission for the file's owner only. The last command launches the app as your current user and displays diagnostic output in the terminal. Don't add sudo when launching a desktop app. Admin privileges for installing dependencies and the user account used to run an app are separate matters.

  1. If you see Permission denied, use ls -l to check the execute bit, then check whether the file's partition is mounted with noexec. Execute permission doesn't override a mount restriction.
  2. An error mentioning FUSE or libfuse.so.2 means the runtime requirements for mounting this AppImage aren't met. Install the required runtime dependency using your distribution's package instructions; package names vary between distributions.
  3. If you see Exec format error, first check that you downloaded the right architecture. If the file isn't recognized as the expected executable, download the installation file again.
  4. If no window appears, keep the original terminal output. AppImage isn't a universal compatibility layer; the graphical session, system libraries, and security policies can all affect startup.

Don't disable security mechanisms as a general fix, and don't assume an AppImage will automatically create a desktop icon or start on login. Check the actual interface and installation results to see whether those integrations are available.

5. First launch: Check installation, subscription, and connection separately

A window appearing confirms only that the app launched; it doesn't prove that a subscription works or that app traffic is being routed through the proxy. The steps below assume you already have your own service provider and subscription. This site doesn't provide, sell, or recommend proxy nodes or subscriptions. Installing the client and obtaining a network service are separate steps.

  1. Check that the app launches

    Open Shadowrocket from your desktop launcher. If you're using AppImage, launch it from a terminal first. Confirm that Home opens before configuring the connection, so you don't confuse an app crash with a network timeout.

  2. Import a subscription

    Tap “+” in the top-right corner of Home, set Type to Subscribe, enter your existing subscription link, and save. The example https://example.com/sub?token=xxxx is fictitious and won't work for a real connection.

  3. Check the configuration

    After updating, confirm that an entry appears in Home. In Config, check which configuration is active, then review Global Routing. Importing a list of nodes and enabling a rule configuration are separate actions.

  4. Test traffic

    After connecting, use the same app to access the same address for comparison. Note whether it times out or reports a DNS error. If a browser works but terminal tools don't, check each program's proxy settings and environment variables.

Linux desktop apps don't all follow the system proxy settings in the same way. When configuring an HTTP or SOCKS proxy, use the actual listening address and port on your machine; don't copy a fixed value from the internet. Troubleshoot traffic interception only if the app explicitly offers and enables a corresponding method. An enabled connection toggle doesn't mean traffic from every process is being routed through the proxy.

6. Global Routing: Distinguish rule issues from connection issues

The package format doesn't change how Global Routing works. When troubleshooting, keep the test target and connection entry fixed, and change only one setting at a time. These comparisons apply to traffic handled by Shadowrocket; they don't mean every program on the system is automatically covered.

Config

Recommended

Let the rules in the active configuration determine the policy. Check the order of rules such as DOMAIN-SUFFIX, IP-CIDR, and GEOIP, and confirm the fallback policy in FINAL. Config doesn't mean that all unmatched traffic will necessarily go direct.

Best for: everyday use with an existing rule configuration.

Proxy

Send traffic handled by Shadowrocket to the selected proxy policy instead of routing it according to domain or address rules in Config. If the result differs from Config, check which rules match and which policy is selected.

Best for: temporarily separating proxy connection issues from rule issues.

Direct

Use the direct policy for traffic handled by Shadowrocket. This won't disable proxies configured separately in other programs, nor does it prove that the current network can reach the test target.

Best for: checking whether the target is reachable by comparing with a direct connection.

If your configuration includes DOMAIN-SUFFIX,example.com,DIRECT, test with the matching domain. Visiting the IP address directly may not match that domain rule. If you use Scene, check the configured scene conditions and corresponding policies; don't treat it as a fixed global routing mode. Restore your usual settings after troubleshooting so temporary tests don't affect later results.

7. Updates, removal, and common installation issues

Package managers track installed DEB and RPM packages, but installing a local file doesn't add a repository that can automatically update Shadowrocket. To update, get a package for your system from this site's download page and install it with the same package manager. Updating an AppImage usually means replacing the file you're running; also check whether any existing desktop shortcuts still point to the old path.

Why doesn't my DEB update automatically?

First check whether the appropriate update source is configured on your system. Installing a local DEB doesn't mean an update repository is available. To update manually, download the file again from the download page, install it using sudo apt install followed by the actual full path, and review the transaction summary.

Which package name should I use to uninstall?

For DEB, get the package name with dpkg-deb --field "$pkg" Package. For RPM, use rpm -qp --queryformat '%{NAME}\n' "$pkg". Pass the actual name returned by the command to apt remove or dnf remove; don't guess from the filename.

Will deleting the AppImage also remove my settings?

Not necessarily. The app file and user configuration are usually stored separately, so deleting the AppImage doesn't necessarily delete your settings. If you need to clean up, use the app's configuration management features first and back up your own configuration. Don't delete files from your user directory based on guessed paths.

The app opens, but the subscription stays empty. What should I check?

First confirm that the item saved in Home uses the Subscribe type. Check that the link is complete, contains no unintended spaces, and that the update didn't return an error. If you contact your existing provider to check the link, avoid exposing its token in public screenshots. Replacing the DEB or RPM won't fix an expired or invalid subscription link.

When reporting an issue, include your distribution name, the output of uname -m, the package format, the stage where it failed, and the original terminal error. Subscription URLs, passwords, and PrivateKey values are sensitive; remove them before sharing logs. Pinpointing whether the problem is a package-manager installation failure, an AppImage launch failure, or a connection failure after launch is more useful than simply saying “Linux doesn't work.”

Download Shadowrocket