Shadowrocket for Linux: Choose and Install a DEB, RPM, or AppImage Package

Choosing a Linux package: check your distribution, then your architecture

Systems that use APT, such as Ubuntu and Debian, generally use DEB packages; Fedora and other systems using DNF generally use RPM packages. Choose AppImage when you need a single-file app. The file extension indicates the package format, not the processor architecture, and doesn't guarantee compatibility across distributions. Check the architecture and system requirements on the download page before downloading.

Run these two read-only commands to identify your basic system details. On a derivative distribution, also check ID_LIKE and confirm which package manager is actually in use. Don't assume every RPM-based system uses dnf; for distributions that use another package manager, follow the system documentation.

cat /etc/os-release
uname -m

Before you download: check the source and full file path

Get the installer from the Linux section of the client download page. Shadowrocket for Linux is free. The iPhone / iPad version costs $2.99 as a one-time App Store purchase; the Mac (Apple Silicon and Intel), Windows, and Android versions are also free. For iPhone / iPad system requirements, refer to the App Store listing.

1. Check your system

   In a terminal, run cat /etc/os-release and uname -m. Note your distribution, package manager, and architecture; don't guess based on your computer's brand.

2. Open the download page

   On this site's Client Downloads page, go to Linux and select the DEB, RPM, or AppImage package that matches your system. Wait for the browser to confirm the download is complete.

3. Find the file path

   In your file manager, open the downloaded file's properties and note its absolute path, including the filename. The download directory may have a localized name or may have been changed, so don't assume it's called Downloads.

4. Choose an installation method

   Install DEB and RPM packages with the system package manager, as described below. For AppImage, follow the single-file steps to add execute permissions. Don't switch between all three formats while troubleshooting the same issue.

The interactive commands below are for Bash. When prompted, paste the actual file's absolute path and press Enter. Paths can contain spaces, but don't add quotes at this prompt or use ~ in place of your home directory; read doesn't expand tildes. Variables in the commands that follow are already quoted.

How to install a DEB package with apt

On Debian, Ubuntu, and compatible APT-based systems, use apt install to install a local DEB package. The package manager can then try to resolve dependencies from configured software repositories. This command takes an absolute file path, not a package name from a repository. Before installing, you can check the package's Package and Architecture fields.

read -r -p "Enter the absolute path to the DEB file: " pkg
test -f "$pkg" && dpkg-deb -f "$pkg" Package Architecture
sudo apt update
sudo apt install "$pkg"

Check that the second line displays package information and no path errors before running the installation command. sudo requests administrator privileges on this machine; password characters usually aren't shown as you type. This isn't an app account login. apt update only refreshes repository indexes; it doesn't install or update Shadowrocket.

• File not found: Check the pasted path, filename capitalization, and whether the download completed. Don't keep retrying with administrator privileges.
• Unmet dependencies: Check the missing package names and system requirements, and make sure your software repositories are available. Don't assemble runtime libraries from unknown sources.
• Package manager is locked: Wait for system updates or other installation tasks to finish, then try again. Don't treat deleting the lock file as a routine fix.
• Installation complete: Look for Shadowrocket in the desktop app menu. If the installer reported an error, resolve it first; seeing an app icon in the menu alone doesn't confirm a successful installation.

How to install an RPM package and resolve dependencies with dnf

On Fedora and compatible systems that use DNF, use dnf install to install a local RPM package. First check the package name and architecture, then review the proposed transaction. DNF may also install runtime dependencies; the exact changes depend on your configured repositories and installed components.

read -r -p "Enter the absolute path to the RPM file: " pkg
test -f "$pkg" && rpm -qp --queryformat '%{NAME} %{ARCH}\n' "$pkg"
sudo dnf install "$pkg"

The installation transaction summary should match your expectations. If it proposes removing many desktop components, reports an architecture mismatch, or shows dependency conflicts, cancel and check the package format. Don't add options to skip dependencies or force replacements just to proceed.

How to run an AppImage: add execute permission and launch it from a terminal

After downloading an AppImage, you usually need to add execute permission before launching it as the current desktop user. Run it from a terminal the first time so you can see any permission, mount, or runtime library errors. If double-clicking does nothing, don't launch the entire graphical app with sudo.

read -r -p "Enter the absolute path to the AppImage file: " app
test -f "$app" && chmod u+x "$app"
"$app"

chmod u+x adds execute permission for the file owner. It doesn't convert the file format or install missing system components. You can launch the file again from the same path. If you move it, use its new path. Don't delete or replace the file while the program is running.

After installation: check that it launches, then review your connection settings

Opening the app and connecting to a network are separate checks. First make sure it launches from the desktop as a regular user, then use connection details provided by a service you already use. Installing the client doesn't automatically create a working server. This site doesn't provide, sell, or recommend nodes or subscriptions.

1. Check that it launches: After installing a DEB / RPM, launch Shadowrocket from the app menu. For AppImage, launch it from its actual file path. If it crashes, keep the terminal error and note your distribution and architecture.
2. Check your connection details: When importing your own configuration, verify that the server address, port, protocol, and credentials are complete. Use the port provided by your service; don't change it to a fixed value based on an installation guide.
3. Understand what the settings do: If the current interface has Home, Config, or Settings, use the labels shown on your device. In Global Routing, Direct means a direct connection. Don't treat results in this mode as a proxy connection test.
4. Check which rules apply: In Config mode, results are also affected by the configuration's rules. Updating a subscription and updating the app are separate tasks: the former updates your connection details, while the latter replaces the client application.

If you see an authorization prompt, confirm that it relates to the action you just started and review the specific permissions requested. Using administrator privileges for installation doesn't mean the app must always run as an administrator. Authorization behavior varies by desktop environment, network routing method, and distribution. Don't use iPhone / iPad VPN prompts to judge whether Shadowrocket installed successfully on Linux.

Update and uninstall: use the actual package name and keep your own configuration

To update a DEB or RPM installation, download the new package in the matching format and install it with the same package manager. Don't judge the result by a change in filename, and don't assume that installing a local package automatically adds an update repository. To update an AppImage, exit the app, replace the old launch file with the new one, and check its execute permission again.

• Uninstall a DEB: Read the Package field from the original installation file, then pass the actual name to APT. Review the transaction summary before uninstalling. Don't use the full installation filename as the package name.
• Uninstall an RPM: Read the NAME field from the original file, then use DNF to remove the corresponding package. Review the dependency changes as well.
• Remove an AppImage: Exit the app and delete the file. If you created a desktop shortcut manually, remove that entry too.
• Keep your configuration: Uninstalling the app may not remove settings from your user directory. Before migrating, use the app's actual export feature to save your configuration. Don't guess the configuration directory or recursively delete unknown directories.

The commands below show how to get the actual package name from a local installation file before uninstalling. Run only the set that matches your installation format. You'll need to enter the absolute path to a file that still exists. If you've already deleted the installer, check the installed package list with your system package manager instead of guessing the name.

# APT-based systems: get the package name from DEB metadata
read -r -p "Enter the absolute path to the original DEB file: " pkg
name=$(dpkg-deb -f "$pkg" Package) && sudo apt remove "$name"

# DNF-based systems: get the package name from RPM metadata
read -r -p "Enter the absolute path to the original RPM file: " pkg
name=$(rpm -qp --queryformat '%{NAME}' "$pkg") && sudo dnf remove "$name"