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

Check your distribution, architecture, and desktop environment

The package format depends on your distribution’s package management system, not its desktop theme. Ubuntu and Fedora both commonly use GNOME, but typically require DEB and RPM packages, respectively. AppImage may suit other distributions, but compatibility still depends on CPU architecture, system libraries, and the desktop environment; it is not guaranteed to run on every Linux system.

cat /etc/os-release
uname -m

The first command shows ID, ID_LIKE, and PRETTY_NAME; the second reports the machine architecture. Common values include x86_64 for x64 and aarch64 for ARM64. Use the architecture actually offered on the download page. Changing a file’s DEB, RPM, or AppImage extension does not change its format or fix an architecture mismatch.

• Debian / Ubuntu: Choose DEB and use apt to install the local file and resolve dependencies available from configured repositories.
• Fedora: Choose RPM and install it with dnf. openSUSE also uses RPM packages, but its package manager is zypper.
• Other desktop distributions: Check whether a compatible AppImage is available, then verify its runtime requirements.
• Headless servers: This guide covers desktop app installation, not background services. Without a graphical session, a missing window alone does not mean the installation is broken.

Get ready in four steps

The filenames in the commands below are convenient local names, not fixed names for packages from this site. In your file manager, rename the downloaded file to the corresponding name before running a command. Or leave its original name and drag the file into the terminal to insert its full path. Do not use a temporary file while the browser is still downloading it.

1. Check your system

   Run cat /etc/os-release and uname -m to note your distribution and architecture. On Debian-based systems, you can also run dpkg --print-architecture to see the architecture name used by the package manager.

2. Get the package

   Open the Linux downloads section and download an available format for your architecture. Do not try to convert a package by changing its extension.

3. Set up the file path

   Place the file in ~/Downloads and rename it according to its format: Shadowrocket.deb, Shadowrocket.rpm, or Shadowrocket.AppImage. If your system uses a different downloads folder, use its actual path.

4. Install and launch

   Run only the command set for the format you chose. After installing a DEB or RPM package, launch the app from the application menu. Run an AppImage file directly. Keep the terminal output when troubleshooting for the first time.

DEB and RPM: Install with your package manager

The ./ before a local package path matters: it tells the package manager to use a file in the current directory rather than look up a package by name in software repositories. Use sudo for installation. Launch the desktop app as a regular user; do not run the entire desktop session as root.

Debian / Ubuntu instructions

cd ~/Downloads
dpkg-deb -f ./Shadowrocket.deb Package Architecture Depends
sudo apt install ./Shadowrocket.deb

dpkg-deb -f reads package metadata; it does not install the app. If apt reports that repository indexes are out of date, run sudo apt update and try again. If it reports an architecture error, download the correct build instead of adding a force-install option. If dependencies cannot be met, note the specific dependency names and your system version. Do not remove core system libraries.

Fedora / openSUSE instructions

cd ~/Downloads
rpm -qp --queryformat '%{NAME} %{ARCH}\n' ./Shadowrocket.rpm

# Fedora
sudo dnf install ./Shadowrocket.rpm

# openSUSE: use this command instead of the dnf command above
sudo zypper install ./Shadowrocket.rpm

RPM is a package format; it does not mean every RPM-based distribution has the same runtime environment. If your package manager reports that a dependency is unavailable, check the download page’s compatibility requirements. Do not ignore dependencies and defer the problem until launch. A successful installation only confirms that the files and package records were added to the system; it does not verify your configuration or network connection.

AppImage: Make it executable and launch from the terminal

AppImages are generally not registered in the system package database like DEB and RPM packages. The app is stored as a standalone file, and you must grant it execute permission before first use. Moving or deleting the file may break existing shortcuts. Keep it in a permanent location rather than a downloads folder that may be cleaned automatically.

mkdir -p "$HOME/Applications"
mv "$HOME/Downloads/Shadowrocket.AppImage" "$HOME/Applications/"
cd "$HOME/Applications"
chmod u+x ./Shadowrocket.AppImage
./Shadowrocket.AppImage

If chmod succeeds but you still get a permission error, use findmnt -T ./Shadowrocket.AppImage to inspect the mount options for the file system. Removable drives and restricted directories may use noexec. Move the file to a user directory where execution is allowed instead of relaxing restrictions on an entire drive. For FUSE-related errors, do not copy library names from another distribution or start with a broad system upgrade.

First launch: Import your configuration, then check Global Routing

Once the window opens, installation is essentially complete. Next, use your existing configuration: manage servers and subscriptions in Home, rule configurations in Config, and client preferences in Settings. Installing the app does not provide these configurations or automatically supply a service you can connect to.

1. In Home, tap “+”, set Type to Subscribe, enter your existing subscription URL, and save. Refresh the subscription after importing and confirm that the expected entries appear. Subscription URLs often contain credentials, so do not include them in public screenshots.
2. In Home, select an existing entry and run Connectivity Test. If the test fails, check the address, port, authentication, and current network. A successful installation alone does not prove the remote server is reachable.
3. In Config, import and select your own rule configuration, then check Global Routing. For an initial connection test, use the controls manually. To configure automatic connections, go to Settings → On Demand; this does not replace protocol settings or routing rules.

If Scene is available in your interface, check the conditions and policies for the selected scene; it is not another name for Config. After changing the mode, make a new request rather than judging the new settings from an existing browser connection. For help checking rule syntax or DNS, see the troubleshooting guide.

Common installation, upgrade, and launch issues