Install Shadowrocket on Linux: Choose a DEB, RPM, or AppImage package

At a glance

This guide is for users installing Shadowrocket on a Linux desktop. Check your distribution and processor architecture first, then choose a DEB, RPM, or AppImage package from this site’s download page. Install it locally, set execution permissions if needed, and check that it launches. The commands use the actual path to your downloaded file, so there’s no need to guess the package name. Connection testing assumes you already have a provider and subscription; installing the app does not provide a working connection.

1. Check your distro, architecture, and package source

DEB, RPM, and AppImage are software distribution formats, not proxy protocols, and they do not replace connection settings. Debian, Ubuntu, and distros using the same package management system generally use DEB packages; Fedora and other systems using dnf generally use RPM packages. Other desktop distros may be able to run an AppImage if the required runtime environment is available, but a “single-file app” is not necessarily compatible with every Linux system.

cat /etc/os-release
uname -m
getconf LONG_BIT

The first command displays distribution details; check ID and ID_LIKE. The second shows the machine architecture reported by the kernel, and the third helps confirm the current user-space bitness. Common architectures such as x86_64 and aarch64 are not interchangeable. Even after choosing the right package format, check the architecture listed on the download page. If there’s no matching package, don’t rename a file or force installation to bypass the check.

Install with a package manager

deb: Debian / Ubuntu: use apt
rpm: Fedora-based distros: use dnf
Permissions: Package operations usually require sudo
Package management: Installation details are recorded in the system package database

Match the package format and CPU architecture separately; the file extension alone isn’t enough.

Run a single file

Format: AppImage
File permissions: Requires execution permission for the current user
Runtime environment: Still depends on the architecture, system libraries, and FUSE
Where to save it: Choose a permanent location in your home directory

AppImage packages aren’t installed with apt or dnf and may not create an application menu entry automatically.

Go to the download page for all platforms and open the Linux section. Packages are provided on this site. There are two ways to get Shadowrocket: the iPhone / iPad app is a one-time $2.99 purchase on the App Store; check the App Store listing for system requirements. The Mac (Apple silicon and Intel), Windows, Android, and Linux versions are free. The iPhone / iPad app is published by Shadow Launch Technology Limited, App ID 932747118.

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

Use apt to install a local package. It checks dependencies during installation and tries to find them in your system’s configured software repositories. Download the file first, then open a Bash terminal and follow the steps below. When prompted for a path, paste the full path to the actual file without adding quotation marks around it. The command already quotes the variable, so paths containing spaces are handled correctly.

Download the DEB package

Open this site’s download page, go to the Linux section, check the architecture, and save the DEB file. Wait until your browser reports that the download is complete; don’t select a temporary file that’s still downloading.
Find the file

Locate the downloaded file in your file manager and check its full path in the file properties. You can also use Tab completion when entering the path in a terminal to avoid mistyping the filename.
Install the package

Run the command below, enter the actual path, and review apt’s installation plan. If the transaction proposes removing unrelated software or reports an architecture mismatch, cancel and investigate before proceeding.
Check that it launches

Once installation is complete, find Shadowrocket in your desktop’s application menu and launch it as a regular user. Confirm that the main window opens before importing your existing configuration.

read -r -p "Enter the full path to the downloaded DEB: " pkg
if [ -f "$pkg" ]; then
  pkg="$(realpath -- "$pkg")"
  dpkg-deb -f "$pkg" Package Architecture
  sudo apt update && sudo apt install "$pkg"
else
  printf '%s\n' "File not found. Check the path."
fi

realpath converts the path to an absolute path so apt knows to install a local file. If you provide a filename without a path prefix, apt may search for it as a package name instead. The network connection used during installation is generally for downloading dependencies; it doesn’t mean the local DEB download is incomplete. If apt update reports repository errors, fix your repositories or network connection before trying again.

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

Use your distro’s dependency resolver to handle RPM files. The command below installs a local RPM with dnf rather than invoking a lower-level installation operation directly. dnf can look for dependencies in enabled repositories, but it can’t resolve every difference between distributions. The fact that a system recognizes RPM files doesn’t mean every RPM package is suitable for it.

read -r -p "Enter the full path to the downloaded RPM: " pkg
if [ -f "$pkg" ]; then
  pkg="$(realpath -- "$pkg")"
  rpm -qp --queryformat '%{NAME} %{ARCH}\n' "$pkg"
  sudo dnf install "$pkg"
else
  printf '%s\n' "File not found. Check the path."
fi

File not found: Check the path and capitalization. Linux filenames are usually case-sensitive. Keep the double quotes in the command if the path contains spaces.
Unavailable dependency: Note the missing dependency, then check your distro and enabled repositories. Don’t add repositories from another distribution indiscriminately.
Signature or trust warning: First confirm that the file came from this site’s download page, then read the full error message. Don’t disable signature checks as a routine installation step.
Architecture mismatch: Compare uname -m with the architecture listed on the download page. Don’t use a force-architecture option to continue.

Once dnf reports that the transaction is complete, launch Shadowrocket from your desktop. If the application menu hasn’t refreshed, log out of your desktop session and back in. Refreshing the menu won’t restore missing files if the installation failed; return to the terminal and address the installation error first.

4. AppImage: Make it executable and run it

An AppImage is usually distributed as a single file. Move it to a permanent location, such as an Applications folder in your home directory, before setting its execution permission. That way, any desktop shortcut you create later is less likely to break if the file is moved. Keep the filename and extension as downloaded; there’s no need to rename it.

read -r -p "Enter the full path to the downloaded AppImage: " app
if [ -f "$app" ]; then
  app="$(realpath -- "$app")"
  chmod u+x -- "$app" && "$app"
else
  printf '%s\n' "File not found. Check the path."
fi

chmod u+x adds execution permission for the file’s owner only; there’s no need to make the file writable by everyone. If the file belongs to another user, first check whether it was downloaded and saved in the right location instead of launching the whole desktop app with sudo. You can also enable execution permission in your file manager’s file properties, though menu labels vary between desktop environments.

AppImage won’t launch? Troubleshoot by error type

Permissions and file location

Permission denied: Check the execution permission shown by ls -l.
Execution permission is set, but access is still denied: Check whether the filesystem is mounted with noexec.
Move the file to a local directory where execution is allowed, set its permission, and try again.

Architecture and runtime dependencies

Exec format error: Check that the package architecture matches your system.
FUSE or libfuse.so.2 is missing: Install the required compatibility library using your distro’s package guidance.
A system library symbol is missing: Check the runtime requirements. Don’t replace core system libraries to force the app to launch.

Run the file directly from a terminal and read the error before troubleshooting. Repeatedly double-clicking it or granting broader permissions won’t identify the cause.

FUSE package names vary by distribution and system version, so one installation command won’t work everywhere. Containers, restricted desktop sessions, and some mount configurations may also block required operations. Being able to open the AppImage window doesn’t mean the system has granted every permission needed for subsequent network activity.

5. First launch: Check installation and connection separately

First, confirm that Shadowrocket opens as a regular user and retains its basic settings. Then test the connection. The package installs the app; your existing subscription and configuration determine the connection target and routing behavior. This guide assumes you already have a provider and subscription. This site does not provide, sell, or recommend nodes or subscriptions, and the app’s purchase price is not a connection plan.

In Home, check for existing connection entries. To add one, tap + in the top-right corner, select Subscribe under Type, enter your existing subscription URL, and save it. Then refresh the subscription.
Check whether the refresh added connection entries. A failed URL, expired authentication, and an app that won’t launch are different issues; reinstalling won’t fix them all.
Open Config to check the current configuration and rules, then choose a routing mode in Global Routing that suits your test.
Read any system permission prompts during the first connection. Grant permission only when clearly prompted; don’t switch to running the app as root all the time.

This comparison explains what each routing mode is for. Choosing Config doesn’t mean every connection will go direct or through a proxy; the result depends on rule order and the assigned policies. Choosing Proxy won’t fix an incorrect address, port, password, or transport setting.

Global Routing → Config

Recommended

Routing follows the rules in your current configuration. Check that they behave as expected, especially how the final FINAL rule handles connections not matched earlier.

Best for: Everyday use and rule testing with an existing routing configuration

Global Routing → Proxy

Test whether the current connection works in proxy mode. This can help distinguish connection setting issues from rule selection issues, but coverage still depends on how the system handles network traffic.

Best for: Briefly checking whether an existing connection can be established—not confirming that every app’s traffic is routed

Global Routing → Direct

Use direct mode as a baseline for your network. If a site is reachable directly, that only confirms that this route works; it doesn’t prove that your proxy connection is working.

Best for: Checking local network, DNS, and site availability

During troubleshooting, leave automatic connection conditions off for now. If Settings → On Demand is enabled, check its triggers to prevent it from reconnecting after you disconnect manually. Don’t use Scene or automation settings as a substitute for basic manual connection testing, and don’t assume that system VPN controls on other platforms work the same way on a Linux desktop.

6. Update, uninstall, and record errors

Before updating, save the configuration you’re using and confirm that you can still manage your existing subscription. To update DEB or RPM installations, use the same package manager with the new file from the download page and review the transaction. Installing a local package doesn’t necessarily add an update repository. For AppImage, quit the app before replacing the file, then check its execution permission and the path used by any desktop shortcut.

Format	How to update	Uninstalling
deb	Use apt to install the matching downloaded package, then check the transaction result.	Remove it with your package manager using the actual package name. Use dpkg-deb to look up the name.
rpm	Use dnf to install the matching downloaded package; don’t force an installation across architectures.	Remove it with dnf using the actual package name. Use rpm to look up the name.
AppImage	Quit the app before replacing the file, and make sure the launcher points to its new location.	Delete the file and any shortcuts you created manually. Check separately whether you want to keep your personal configuration.

Removing the app doesn’t necessarily remove your personal configuration. If the app won’t launch, don’t delete your entire home directory or remove files from unknown locations. Keep your configuration and record the error first. When contacting technical support, provide your distribution, architecture, package format, installation command, and terminal error. Remove subscription tokens, passwords, and private keys from your report.

Installation failed: Record the first key error from apt or dnf, any missing dependencies, and whether the transaction completed.
Launch failed: Note whether the window opens, any AppImage errors in the terminal, and the execution permission and mount settings.
Connection failed: Record the current Global Routing mode, the subscription refresh result, and what happened during the connection attempt. Don’t describe every issue as “the app won’t install.”

After separating these stages, you can usually narrow the issue down to the package format, architecture, dependencies, execution requirements, or connection settings. Troubleshooting each layer is more effective than repeatedly switching between package formats, and helps avoid deleting saved configuration when the installation itself is working.