Use native packages first on Debian, Ubuntu, and Fedora. If no suitable native package is available, check that your system meets the AppImage requirements. This guide covers identifying your distro and CPU architecture, installing local packages, launching an AppImage, and troubleshooting missing dependencies and permission errors.
Check your distro and CPU architecture
Open a terminal on the Linux desktop where you plan to run Shadowrocket and execute the two commands below. The first shows your distro ID and release version; the second reports the machine architecture detected by the current kernel. If you’re using the app in a virtual machine, run these checks inside the VM and choose a package based on its details—not the host system’s.
grep -E '^(ID|ID_LIKE|VERSION_ID)=' /etc/os-release
uname -m
Identify your system
ID=debianorID=ubuntuindicates a DEB package;ID=fedoraindicates an RPM package. For a derivative distro,ID_LIKEcan provide a clue about its lineage, but it does not guarantee that all package dependencies will be met. Check the supported systems listed on the download page before downloading.Check the architecture
x86_64and theamd64architecture commonly used for DEB packages refer to the same architecture class. Likewise,aarch64corresponds to the commonly usedarm64label. On Debian or Ubuntu, you can also rundpkg --print-architectureto check the architecture name used by the package manager. If there’s no build for your architecture, don’t try to work around it by changing the file extension or forcing installation.Get the installer
Open the app download page and choose the Linux package format and architecture that match your system. Once the download finishes, open the folder your browser saved it to using your file manager. Check the full filename, including the extension, and watch for a number the browser may add if a file with the same name already exists.
Open the download folder
If your desktop environment provides an option to open a terminal in the current folder, use it. Otherwise, use
cdin a terminal to navigate to the download folder. Runpwdandls -lto confirm the location and filename. The examples below uselocal.deb,local.rpm, andlocal.AppImage; replace these with the full names of your downloaded files. Keep quotation marks around filenames that contain spaces.
Debian and Ubuntu: Install a DEB with apt
Run the following commands from the folder containing the package. ./ tells apt to work with a file in the current folder instead of searching your software repositories for a package with the same name. apt checks the local package’s dependencies and tries to resolve any missing ones from your configured repositories.
dpkg-deb -f "./local.deb" Package Architecture Depends
sudo apt install "./local.deb"
The first command only reads package information, so you can check the package name, architecture, and dependencies. The second command installs the package. Before confirming, review the list of packages to be added, upgraded, or removed. If a large number of unrelated packages are marked for removal, cancel and check distro compatibility and your repository configuration.
- Missing dependencies: If your software repositories are configured correctly, run
sudo apt updateto refresh the package index, then try installing again. If the update succeeds but a dependency still has no installation candidate, note the package name and version requirement in the error, then check whether your distro meets them. - Architecture mismatch: Compare the
Architecturevalue reported bydpkg-debwith the output ofdpkg --print-architecture. Resolve the mismatch by getting a package for the correct architecture. Don’t change your system’s architecture configuration just to install a desktop app.
Fedora: Install an RPM with dnf
On Fedora, use dnf to install a local RPM. It resolves the installation transaction and attempts to retrieve dependencies from enabled repositories. The rpm -qp command below only reads metadata from the package file; it does not install the app.
rpm -qp --queryformat '%{NAME} %{ARCH}\n' "./local.rpm"
sudo dnf install "./local.rpm"
Both native package formats are tracked by their respective package managers. To check whether a package is installed or remove it, use the package name you found in the previous checks—not the downloaded filename.
DEB package record
- Package details
dpkg-deb -f "./local.deb" Package Architecture- Check installation status
dpkg-query -s actual-package-name- Uninstall command
sudo apt remove actual-package-name
Replace “actual package name” in the command with the value of the Package field.
RPM package record
- Package details
rpm -qpi "./local.rpm"- Check installation status
rpm -q actual-package-name- Uninstall command
sudo dnf remove actual-package-name
Replace “actual package name” in the command with the NAME reported by rpm -qp.
If dnf reports an unsatisfied dependency, check which package or library is missing. Then use dnf repolist --enabled to verify that the required repositories are enabled. If there’s a conflict, don’t force the installation by ignoring dependencies. An incomplete installation transaction is different from an app that installed successfully but won’t open.
AppImage: Make it executable and launch it
If no suitable DEB or RPM package is available, you can try an AppImage once you’ve confirmed that its architecture and runtime requirements match your system. Save it in a fixed location that’s writable by your user and allows executable files. The command below uses u+x to grant execute permission only to the file owner—a more specific form of chmod +x. Run both commands as a regular desktop user.
chmod u+x "./local.AppImage"
"./local.AppImage"
You can launch an AppImage directly from a terminal. Setting its executable permission does not register it as a system package, and it may not appear in your application menu automatically. The comparison below covers two ways to deploy Shadowrocket; the recommended option assumes a suitable native package is available on the download page.
Registered with a package manager
RecommendedInstall with apt or dnf, then check the package status or uninstall it by name. If the package was installed locally and no repository provides updates for it, download the new version and reinstall it with the same package manager.
Best for: systems with a compatible DEB or RPM package, when you want to manage installation records with system tools
Run independently as a user
Launch the AppImage directly from its folder. Before replacing it, close the running app and grant execute permission to the new file. If you created a launcher shortcut, make sure it points to the new file location.
Best for: systems without a compatible native package, when you want to keep an executable in your user directory
App won’t open after installation: Troubleshoot by error
First, identify where the problem occurs. If the package manager didn’t finish installing, address the first specific error in the installation transaction. If the package is installed but no window appears, reproduce the launch issue in your current desktop session. Launching an AppImage from a terminal can reveal errors that aren’t visible when you double-click it.
Already ran chmod, but still getting Permission denied?
First, run ls -l "./local.AppImage" and check that the file owner’s permission bits include x. Then run findmnt -T "./local.AppImage" -o TARGET,OPTIONS to check the mount options. If you see noexec, changing the file permissions won’t make it executable in that location. Move it to a user directory where execution is allowed and try again; there’s no need to change system mount settings.
Terminal says libfuse.so.2 is missing. What should I do?
This means the AppImage runtime can’t find a FUSE 2 compatibility library. Check which package your distro’s repositories provide—libfuse2, libfuse2t64, or another equivalent—and install the compatible library using your distro’s package manager. Don’t remove existing FUSE 3 components. If your system policy doesn’t allow the required FUSE functionality, check first for a compatible native package.
Getting Exec format error? Is it a permissions issue?
Start by checking the file format and architecture, rather than running chmod again. If the file command is available, run file "./local.AppImage" and compare the result with uname -m. If it reports a different CPU architecture, return to the download page and choose the right package. If it identifies the file as an HTML document, the download isn’t an executable package; download it again.
Package installed, but it’s missing from the app menu?
First, search for Shadowrocket in your current desktop session. If it still doesn’t appear, run dpkg-query -L actual-package-name or rpm -ql actual-package-name to check whether the package includes a .desktop launcher. If you’re using only a remote terminal or don’t have a desktop session, a successful installation doesn’t mean a graphical window can appear. If an AppImage has no menu entry, launch it using the terminal command in the previous section.