Install Shadowrocket on Linux: Choose a DEB, RPM, or AppImage (apt, dnf, chmod +x)

Choose a package for your distro: install DEB packages with apt on Debian or Ubuntu, RPM packages with dnf on Fedora, or make an AppImage executable and run it.

At a glance

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
  1. Identify your system

    ID=debian or ID=ubuntu indicates a DEB package; ID=fedora indicates an RPM package. For a derivative distro, ID_LIKE can 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.

  2. Check the architecture

    x86_64 and the amd64 architecture commonly used for DEB packages refer to the same architecture class. Likewise, aarch64 corresponds to the commonly used arm64 label. On Debian or Ubuntu, you can also run dpkg --print-architecture to 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.

  3. 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.

  4. Open the download folder

    If your desktop environment provides an option to open a terminal in the current folder, use it. Otherwise, use cd in a terminal to navigate to the download folder. Run pwd and ls -l to confirm the location and filename. The examples below use local.deb, local.rpm, and local.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.

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

Recommended

Install 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.

Download Shadowrocket