Linux Installation and Package Formats

1. Check Your Distribution and Architecture

Choose a Linux package for your current system, not its desktop environment. GNOME, KDE, and other desktops do not determine whether to use deb or rpm. Ubuntu and Fedora may look similar while using different package management systems. Run these two read-only commands in a terminal to check your distribution ID and machine architecture.

cat /etc/os-release
uname -m

In the first command's output, look for ID and ID_LIKE, and consult your distribution's package management documentation. The second command commonly returns x86_64 or aarch64. These usually correspond to x64 and ARM64 in the download instructions, respectively. Package format and architecture are separate requirements: the same file extension does not guarantee processor compatibility. If the download page does not offer a build for your architecture, do not try to install a package built for another one.

2. Get the Package and Prepare the Local File

Get the package from the Linux section of the download page. Check its format and architecture before saving it. This guide does not use third-party download links or fetch remote installation scripts from the terminal. If the browser is still downloading the file, its size is zero, or it still has a temporary extension, wait for the download to finish.

1. Create a shadowrocket-install folder in your home directory.
2. Put only the package you selected in this folder. Do not mix it with other apps or older packages.
3. To make the commands below easy to copy, rename the deb file to shadowrocket-local.deb or the rpm file to shadowrocket-local.rpm. See section 5 for where to save an AppImage.
4. Change the filename only; changing the extension does not convert the package format. Renaming the file does not change its architecture or dependencies.

mkdir -p "$HOME/shadowrocket-install"
cd "$HOME/shadowrocket-install"
ls -lh

These filenames are local names you choose on your computer, not the original filenames used for packages on this site. If you keep the downloaded filename, replace the full file path in the commands that follow. Enclose paths containing spaces in English double quotes. Do not run both the deb and rpm instructions.

3. Install a Local deb Package with apt

On Debian, Ubuntu, and other apt-based systems, first change to the folder you created, then install the local deb package. The ./ in the command matters: it tells apt that the argument is a file in the current directory, not a package name from a software repository. Installation requires administrator authorization. Dependencies usually come from your configured system repositories, so a working internet connection may be needed to download them.

cd "$HOME/shadowrocket-install"
sudo apt install ./shadowrocket-local.deb

1. Review the new, upgraded, and removed packages listed by apt. If the transaction proposes removing a large number of packages unrelated to this installation, cancel it instead of confirming.
2. Confirm the transaction and wait for it to finish. Once the terminal prompt returns without an installation error, look for Shadowrocket in your desktop's application list.
3. If the file cannot be found, run pwd and ls -lh to check the directory and filename before changing the installation command.
4. If the architecture is incompatible, return to the download page and check the package architecture. If dependencies cannot be satisfied, check the supported systems, repository configuration, and dependency names.

sudo apt update refreshes the repository indexes; it does not upgrade the entire system or install Shadowrocket. If the error specifically mentions outdated indexes, run this command and retry the local installation. Refreshing indexes repeatedly will not fix an incompatible runtime environment if your system version cannot provide the required dependencies.

4. Install an rpm Package with dnf and Review the Transaction

On Fedora and other dnf-based systems, local installation works much like it does with apt, but the argument must be an rpm file. dnf checks the package metadata for architecture and dependencies, then shows the proposed transaction. Close any running instance of Shadowrocket before installation so an old process does not keep using outdated files while the app is updated.

cd "$HOME/shadowrocket-install"
sudo dnf install ./shadowrocket-local.rpm

• File not found: Check the current directory and file extension. Make sure you did not rename a deb file with an rpm extension.
• Missing dependency provider: Note the missing dependency and check distribution compatibility and repository status. Do not download a system library with the same name and overwrite an existing file.
• Package conflict: Check whether you have another package format or an older package installed. Use your system package manager to review installed packages; do not manually delete app files from system directories.
• Transaction canceled: Review the message shown before cancellation. Determine whether you declined the transaction, encountered a permissions issue, or failed a dependency check before deciding what to do next.

Once installation is complete, launch the app from your desktop's application list. If its launcher does not appear right away, refresh the application list or sign out and back in to your desktop session. Do not assume the installation failed just because you cannot see an icon. If the terminal reported that the transaction failed, resolve the installation error instead of repeatedly clicking the launcher.

5. Run an AppImage from the Terminal

An AppImage is usually saved and run as a single file. Unlike deb and rpm packages, it does not create the same kind of package manager transaction. That does not guarantee it will work in every Linux environment: processor architecture, system libraries, the graphical session, and the FUSE mechanism used by some builds can all affect startup. Check the download page's requirements before choosing this format.

Create an Applications folder in your home directory, move the completed AppImage into it, and rename the file to Shadowrocket.AppImage in your file manager. Then run the command below. chmod u+x adds execute permission for the file owner only; there is no need to make the app writable by everyone.

mkdir -p "$HOME/Applications"
cd "$HOME/Applications"
chmod u+x ./Shadowrocket.AppImage
./Shadowrocket.AppImage

If you see Permission denied, check not only the execute bit but also whether the file's partition is mounted with noexec. For FUSE-related errors, check your distribution's documentation for the required runtime components; their names are not the same across all distributions. An AppImage not appearing automatically in the application menu does not mean the file is damaged.

6. First Launch: Check Installation and Connectivity Separately

Opening the main window confirms only that the app started. Next, configure a server or subscription you already have. This site does not provide, sell, or recommend servers or subscriptions. For the first check, keep your current network connection available. In Home, review the imported details and make sure the address, port, and authentication fields are complete before connecting. Do not enter an arbitrary port just to make a test pass.

1. In Home, import a configuration you already have. A subscription is an updateable source of configuration, not part of the installation package.
2. Check that the selected item is the server you intend to use, not an outdated entry.
3. Check the current Global Routing mode, then run a specific access test. Note the original setting before switching modes, and restore it when the test is complete.
4. If the window works but the connection fails, check authentication, connection timeouts, DNS resolution, and rule matches separately. Troubleshoot the configuration first; do not immediately uninstall and reinstall the app.

7. Updates, Uninstallation, and Common Errors

Before updating, use the app's export feature to back up your configuration and store your subscription credentials securely. Package manager records for deb and rpm packages work differently from replacing an AppImage file. Downloading a new package from this site does not automatically switch the process that is currently running. After updating, quit the old process, reopen the app, and check that your configuration is still there.

• Update a deb package: Download a package for the correct architecture, then use the local apt install method. The package manager will determine whether it is an upgrade based on the package metadata.
• Update an rpm package: When using local dnf install, check that the transaction identifies the expected update. Do not ignore downgrade or conflict warnings.
• Update an AppImage: Quit the app, replace the old file, and check its execute permission again. The newly downloaded file may not retain the previous file's execute bit.
• Uninstall: For deb and rpm packages, confirm the exact package name in your system's package manager before removing it. For an AppImage, quit the app, then delete the file and any shortcuts you created. Check separately whether you want to keep your personal configuration; removing the app does not necessarily delete all user data.