This guide is for Linux devices with a desktop environment. First, check your distribution and system architecture in a terminal, then choose a Shadowrocket installer from the download guide. DEB and RPM packages are registered with the system package manager, while an AppImage runs as an executable file. The steps below cover installation commands and how to troubleshoot dependency, permission, and first-launch errors.
Before you install: Check your distribution and architecture
Your distribution and package manager determine the package format; your system architecture determines whether the program can run on your device. Check both on the system where you plan to install Shadowrocket. For example, if you are installing it in a virtual machine, use the output from inside the VM—not the host machine's device specifications.
-
Identify your distribution
Open a terminal and check
IDandID_LIKEin/etc/os-release.ID=debianorID=ubuntuindicates a DEB package;ID=fedoraindicates an RPM package. For a derivative distribution, useID_LIKEas a guide, then verify its package manager and the supported distributions listed on the download page. -
Check your system architecture
Run
uname -mto check the kernel architecture.x86_64usually corresponds to theamd64label for DEB packages;aarch64corresponds toarm64. For a DEB installation, also rundpkg --print-architectureand use the architecture reported by the package manager. -
Choose an installer
Open the Shadowrocket download guide and check the Linux section for the package format and architecture. For other distributions, first check whether a compatible AppImage is available. If the page does not offer a package for your architecture, do not try to work around it by changing the file extension or forcing installation.
-
Launch and verify
Follow the steps below for your package format. After installing a DEB or RPM package, look for Shadowrocket in your desktop's application menu. You can run an AppImage directly from a terminal. Once the window opens, check that
Homedisplays correctly. If it does not open, note the first error shown in the terminal and use the troubleshooting tips below.
grep -E '^(ID|ID_LIKE)=' /etc/os-release
uname -m
Use apt on Debian or Ubuntu, and dnf on Fedora
Run only the command group for your system. These examples are for Bash. When prompted, paste the absolute path to the actual file and press Enter; do not add quotes around your input. The double quotes in the commands below are intentional: they keep a path with spaces together as a single argument. Check the package information first, then run the installation command.
deb
- Supported distributions
- Debian、Ubuntu
- Installation tool
apt install- Inspect local package
dpkg-deb -f- Removal tool
apt remove
When uninstalling, use the value in the Package field, not the downloaded filename.
rpm
- Supported distributions
- Fedora and compatible distributions that use dnf
- Installation tool
dnf install- Inspect local package
rpm -qpi- Removal tool
dnf remove
When uninstalling, use the value in the Name field, and review the transaction summary first.
Install a DEB package
read -r -p 'Enter the absolute path to the DEB file: ' pkg
dpkg-deb -f "$pkg" Package Architecture
sudo apt install "$pkg"
apt resolves required dependencies from your configured repositories. A filename without a directory may be interpreted as a package name from a repository, so use an absolute path here. If the dependency list comes from stale package indexes, run sudo apt update and try again. If a dependency still has no installation candidate, do not mix repositories from different distributions; first check the system requirements for the package you downloaded.
Install an RPM package
read -r -p 'Enter the absolute path to the RPM file: ' pkg
rpm -qpi "$pkg"
sudo dnf install "$pkg"
rpm -qpi displays information about a local package; it does not install it. Use dnf to resolve dependencies from your enabled repositories and install the package. If the transaction summary proposes removing software unrelated to this installation, cancel and check the package's supported distributions and your repository configuration. Do not bypass dependency checks.
AppImage: Add execute permission and launch from a terminal
An AppImage generally does not need to be registered with the system package manager. You can move it to a permanent location in your home directory, then grant the file owner execute permission. As above, enter the absolute path to the actual file. You do not need sudo to run the program.
read -r -p 'Enter the absolute path to the AppImage file: ' app
file -- "$app"
chmod u+x -- "$app"
"$app"
filereports HTML or plain text: The download may be a web page rather than the program file. Return to the download guide and choose the correct package; changing the file extension will not help.chmodsucceeds, but you still seePermission denied: Runfindmnt -no OPTIONS --target "$app"to check the mount options for the file system. If they includenoexec, move the file to a location where execution is allowed. You do not need to change the mount options for the entire disk.- The terminal specifically reports that
libfuse.so.2is missing: Check your distribution's repository documentation to find the FUSE 2 compatibility package that provides this library. Having FUSE 3 installed does not mean this library is available, and you should not uninstall your existing FUSE 3 installation to resolve the issue.
After the first launch: Separate installation issues from routing issues
If Home opens, the program has launched, but that alone does not confirm that the connection or rules are working. If you already have a configuration and connection details, check the current file in Config, then return to Home and review Global Routing. The two settings below help distinguish rule-based routing from a direct-connection baseline. Switching modes only checks behavior after launch; it will not fix installation dependencies.
Config
RecommendedRequests are handled according to the rules in the current configuration. Test with a domain you know should match a rule. If the configuration ends with FINAL, also try a request that does not match an earlier rule to check the fallback behavior.
Use when: You already have a configuration and want to check that rules are routing traffic as expected.
Direct
Traffic goes direct, so do not use this result to judge whether your rules are correct. Switch temporarily, then test the same direct-access destination on the same network. Restore your original setting when you finish the comparison.
Use when: Checking whether a destination is reachable directly on your current network.
Common installation, update, and removal questions
Ubuntu downloaded an RPM. Do I need to convert it?
No. Return to the download guide and choose a DEB package that matches the output of dpkg --print-architecture. Changing the file extension does not change the package's internal metadata or dependencies.
Double-clicking an AppImage does nothing. How can I find the problem?
Launch it from a terminal as described above. Check whether the error is about permissions, a missing library, or Exec format error. For the last case, compare the file and system architectures using file and uname -m. Repeating chmod will not fix an architecture mismatch.
Do I need to uninstall the old package before updating?
Exit the app and back up any configuration you want to keep. You can install a newer DEB or RPM package with the same package name and architecture using the same installation command. Check that the transaction summary shows an upgrade. Registering a local package with the package manager does not mean it will be updated automatically from your system repositories.
Does deleting the downloaded file uninstall the app?
For DEB or RPM packages, deleting the downloaded file does not remove the installed program; uninstall it with the relevant package manager. For an AppImage, exit the program, then delete the executable and any manually created desktop shortcut that still points to it. User configuration and program files are separate, so check whether you want to keep the configuration before removing it.