On the computer running your Linux desktop, first check your distribution and processor architecture. For Debian and Ubuntu, choose a DEB package compatible with your system; for Fedora, choose a compatible RPM. Choose AppImage if you don’t need package-manager integration and your system meets its requirements. The steps below cover installation or launch, plus how to tell dependency errors from permission and connectivity issues.
Choose a package: check your distribution, then your architecture
Open a terminal on the computer where you’ll run Shadowrocket. If you’re using a virtual machine, run these commands inside it; don’t choose a package based on the host’s information. The first command prints the system name and distribution ID. The second shows the machine architecture reported by the current system.
grep -E '^(PRETTY_NAME|ID|ID_LIKE)=' /etc/os-release
uname -m
| System or requirement | Format to check first | Before installing |
|---|---|---|
| Debian、Ubuntu | deb | The package matches your distribution, and the required dependencies are available from your configured repositories |
| Fedora and other distributions that use DNF | rpm | The package explicitly supports your system; the same file extension does not mean packages can be mixed across distributions |
| You don’t want the program registered with the system package manager | AppImage | The package architecture matches, its location permits execution, and your system meets the runtime requirements |
x86_64 is usually labeled amd64 in DEB architecture fields; aarch64 usually corresponds to arm64. These are equivalent architecture labels, not a guarantee that the download page provides a build for each one. Choose a package listed in the Linux downloads section that matches your system. If only a different architecture is available, don’t try to work around it by renaming the file or forcing installation. ID_LIKE indicates a distribution family; it does not confirm compatibility.
Install a DEB or RPM package, or launch AppImage
The commands below use Bash. Find the downloaded file in your file manager, then run the corresponding code block. When prompted, paste the full file path, starting with /; you don’t need to add quotation marks yourself. Use just one of the three formats; don’t run them in sequence.
Locate the package
Open your browser’s downloads list and use the entry to open the folder containing the file. Make sure the download is complete, and distinguish the actual package from temporary download files. Use your file manager’s copy-path option to avoid omitting the extension or selecting a similarly named file for a different architecture.
Install a DEB with APT
apt installaccepts a local DEB path and tries to resolve dependencies from your configured repositories. Review the transaction summary, including packages to be installed, upgraded, or removed, before proceeding. If it proposes removing a large number of unrelated packages, cancel first.read -r -p 'Enter the full path to the DEB file: ' pkg sudo apt install -- "$pkg"Install an RPM with DNF
dnf installreads a local RPM and resolves dependencies from enabled repositories. Don’t add an automatic confirmation option; review the transaction DNF proposes first. If there’s a conflict, note the package names in the error instead of installing while skipping dependency checks.read -r -p 'Enter the full path to the RPM file: ' pkg sudo dnf install -- "$pkg"Run AppImage
Place the file in a directory you own where execution is permitted. As a regular user, make it executable and launch it. The AppImage file is the launcher; if the terminal reports an error, save the output and don’t retry with
sudo.read -r -p 'Enter the full path to the AppImage file: ' pkg chmod +x -- "$pkg" && "$pkg"Confirm the window opens
After a successful DEB or RPM installation, search for Shadowrocket in your desktop’s application list. Launch AppImage from where you saved it; it may not add an application menu entry automatically. An open window confirms only that installation or launch succeeded. Get nodes and subscriptions from your service provider; test connectivity after configuration is complete.
Launch, update, and remove the installation
The package format determines how the program files are managed. Before troubleshooting, check whether you’re launching a package-manager installation or a standalone AppImage. If you’ve tried both, close any running windows first, then launch from a known location so you don’t mistake an older file’s behavior for a problem with the new package.
deb / rpm
- Installation record
- Registered with the system package manager
- Find the package name
- For a local file, use
dpkg-deb -f "$pkg" Packageorrpm -qp --queryformat '%{NAME}\n' "$pkg" - How to update
- A local installation doesn’t mean an update repository is configured. To update manually, use a new package compatible with your system
- How to remove
- Use
sudo apt removeorsudo dnf remove, followed by the package name you found. Review the transaction before proceeding
Remove the package by its package name, not the downloaded filename. Deleting the downloaded package won’t uninstall the program.
AppImage
- Launch method
- An AppImage file with execution permission
- File location
- Keep it in a personal directory where execution is allowed, not in a temporary directory that may be cleared
- How to update
- Close the old program, make the new file executable, and remove the old file only after confirming the new one opens
- How to remove
- Close the program and remove the AppImage file. If you created a shortcut manually, remove the old shortcut too
Deleting the launcher doesn’t remove your personal configuration. When troubleshooting with another package, keep the configuration so you change only one variable at a time.
Common installation errors: troubleshoot from the terminal output
APT can’t process the file. What should I check first?
First, make sure you entered the full file path, not the download URL from your browser. Keep pkg set to the path you just entered, then check the file type with file -- "$pkg". If the result identifies an HTML document, you downloaded a web page, not a DEB. Download the package again from the download page; changing the file extension won’t help.
Architecture mismatch or “Exec format error”?
Run uname -m again and compare its output with the architecture listed for the download. For a DEB, check the package metadata with dpkg-deb -f "$pkg" Architecture; for an RPM, use rpm -qp --queryformat '%{ARCH}\n' "$pkg". If the architecture is wrong, choose another package. If it matches, check the file type and make sure the download completed.
A dependency is missing. Should I switch repositories?
Note the first unsatisfied dependency and its version constraint, then confirm the package supports your distribution. On Debian or Ubuntu, run sudo apt update to refresh repository indexes. With DNF, check enabled repositories using dnf repolist --enabled. If your distribution’s standard repositories still can’t satisfy the dependency, don’t add repositories from another distribution.
AppImage is executable, but still reports “Permission denied”
Use ls -l -- "$pkg" to confirm the current user can execute the file, then check the filesystem mount options with findmnt -no OPTIONS --target "$pkg". If the options include noexec, move the file to a personal directory where execution is allowed, update the path, and try again. Don’t change the mount policy for an entire disk just to run one application.
AppImage reports that libfuse.so.2 is missing, but FUSE is installed
This error points to the FUSE 2 userspace library; having FUSE 3 installed doesn’t mean the system also has libfuse.so.2. Look for a compatible package that provides the library in your distribution’s repositories, and make sure its installation won’t remove existing system components. If no compatible package is available, use a DEB or RPM listed on the download page that supports your system.
The window opens, but websites don’t load: distinguish routing from installation issues
Once the window opens normally, don’t reinstall to test the network. First, check whether the same test page loads over a regular network connection, then check Global Routing in the client. The comparison below applies if these options are available in your interface. When switching options, keep the test page and all other settings unchanged.
Config
RecommendedChoose a policy based on the rules in your current configuration. For testing, use one address known to match a proxy rule and another expected to connect directly. A direct connection working on its own doesn’t confirm that the proxy route is working.
Best for: testing proxy and direct rules separately after configuration.
Direct
Connect traffic handled by the client directly, without using a proxy route. If the same address loads under Direct but fails under Config, check the matching rule and selected policy rather than changing the package format. Restore the original routing option after testing.
Best for: comparing direct connectivity to the same test address.