Install v2rayN on Linux: deb and rpm packages, autostart setup

Before you install: check your distribution, architecture, and setup

v2rayN is a desktop client, and its Linux GUI uses Avalonia. The client manages configurations, starts the core, and displays logs; the selected core handles proxy connections. Installing the desktop package does not create a system service that runs at boot, nor does it automatically route every app through the proxy.

Run these two commands first. If uname -m returns x86_64, choose the x64 package; if it returns aarch64, choose arm64. Your distribution determines whether to use a deb or rpm package. Don’t infer the architecture from your computer’s brand.

cat /etc/os-release
uname -m

For the commands below, rename the downloaded package to v2rayN.deb or v2rayN.rpm and place it in ~/Downloads. This is just a local filename, not the package’s original name. If your downloads are in another directory, navigate there first. Get the package from the client download page, and don’t try to force-install a package built for a different architecture.

Debian and Ubuntu: install a local deb package with apt

Use apt install ./filename whenever possible. The ./ prefix identifies a local file, and apt resolves the package’s declared dependencies using your enabled repositories. You can also unpack a package with dpkg -i, but it won’t automatically download missing dependencies, so it shouldn’t be your only step for a first-time install.

cd ~/Downloads
dpkg --print-architecture
dpkg-deb -f ./v2rayN.deb Package Version Architecture
sudo apt update
sudo apt install ./v2rayN.deb

1. Check package details

   Compare your system architecture with the package’s Architecture field. Note the Version field too, so you can include both the client and system versions when troubleshooting.

2. Install dependencies

   Review apt’s installation plan. If it proposes removing a large number of desktop components, cancel rather than using force options to bypass the conflict.

3. Launch it manually for the first time

   Find v2rayN in your desktop app menu and launch it as your current user. The install command requires sudo; launching the GUI does not.

4. Capture error output

   If no window appears, check the Exec field in the desktop launcher file, then run the corresponding program from a terminal and capture the full error output.

If an earlier dpkg install left the package unconfigured, run the repair command below. It may install dependencies or propose removing packages with unresolved dependencies; review the plan before continuing. If your repositories are unreachable, fix your network or repository configuration first. Repeatedly unpacking the package won’t fix download failures.

sudo apt --fix-broken install
sudo dpkg --configure -a

Fedora and openSUSE: install rpm packages with your distribution’s package manager

rpm is a package format, not a guarantee of compatibility across distributions. Fedora uses dnf, while openSUSE uses zypper; use your system’s package manager to resolve dependencies. Check the package details and confirm its architecture and version before running the install command for your distribution.

cd ~/Downloads
rpm -qp --queryformat '%{NAME} %{VERSION}-%{RELEASE} %{ARCH}\n' ./v2rayN.rpm

# Fedora
sudo dnf install ./v2rayN.rpm

# openSUSE: use this command; don’t repeat the dnf command above
sudo zypper install ./v2rayN.rpm

If installation succeeds but the app won’t launch, distinguish between satisfied package dependencies and an available graphical environment. A missing graphical session, display environment variables, or a remote terminal not connected to the desktop can all prevent the GUI from opening. Don’t use sudo to mask these problems.

First launch: verify the local listener before enabling the system proxy

Import a node or subscription you already have, select an available node, and verify that the core is listening. A subscription contains server connection details; an arbitrary address won’t work as a test. Check that the protocol and transport combination is supported by your current core, and review the logs again after switching cores.

In versions that provide these menu items, go to “Settings” → “Parameter Settings” → “Basic Settings” to check the local listening port. Port numbers and menu names can change between versions, so use the values shown in your client. The examples below use an HTTP proxy listening on 127.0.0.1:10808 for troubleshooting; you don’t need to replace your existing settings.

ss -lntp 'sport = :10808'
curl --proxy http://127.0.0.1:10808 --max-time 15 -I https://example.com/

The first command checks for a TCP listener; the second explicitly sends an HTTP proxy request to a test site. If the port provides SOCKS only, use socks5h://127.0.0.1:10808 instead; the proxy resolves the hostname. If nothing is listening, check for core startup errors first rather than assuming the connection is slow.

• A successful request through an explicitly specified proxy confirms that this request made it through the proxy chain. It doesn’t mean every app is using the proxy.
• To route desktop apps through the proxy, use the client’s “System Proxy” → “Set system proxy” option. Which apps it affects depends on your desktop environment and the apps themselves.
• Command-line programs may not use desktop proxy settings. Set a proxy option or environment variable for the program instead.
• For your first setup, verify standard proxy mode. Configure TUN permissions and routing separately to avoid introducing multiple variables at once.

Desktop autostart: use a per-user login entry

For a desktop client, “start at boot” usually means launching automatically after you sign in to the graphical desktop. XDG Autostart is the recommended approach: reuse the desktop file provided by the package, keeping its correct Exec command, icon, and launch options. This avoids guessing the main program’s location and running the entire client as root.

First, check whether “Settings” → “Parameter Settings” in the client offers a “Start automatically at boot” option. If your version already creates a working per-user startup entry, use it as is; don’t create another one, or the client may launch twice at login. To configure autostart manually, locate the desktop file included in the package first:

find /usr/share/applications -maxdepth 1 -type f -iname '*v2rayn*.desktop' -print

Only run the copy command below if you find exactly one matching file. The script checks the number of matches so it won’t arbitrarily choose one of multiple desktop launchers. If there are no matches, inspect the package contents with dpkg-deb -c for deb or rpm -qlp for rpm, and confirm the desktop file’s actual name and location.

bash <<'BASH'
mapfile -t entries < <(find /usr/share/applications -maxdepth 1 -type f -iname '*v2rayn*.desktop')
if [ "${#entries[@]}" -ne 1 ]; then
  printf 'Exactly one desktop entry is required; found %s.\n' "${#entries[@]}"
  exit 1
fi
target="${XDG_CONFIG_HOME:-$HOME/.config}/autostart"
mkdir -p "$target"
cp -- "${entries[0]}" "$target/v2rayN.desktop"
chmod 644 "$target/v2rayN.desktop"
grep -E '^(Type|Name|Exec|TryExec|Hidden|OnlyShowIn|NotShowIn|X-GNOME-Autostart-enabled)=' "$target/v2rayN.desktop"
BASH

• Type should be Application. Make sure the program specified by Exec exists.
• If Hidden=true or X-GNOME-Autostart-enabled=false is present, edit the file in a text editor before testing.
• OnlyShowIn and NotShowIn can restrict which desktop environments show the launcher; check these entries after copying the file.
• Don’t put ~, pipes, or shell redirections directly in Exec; desktop files don’t interpret these as a regular interactive shell would.

After saving, log out and sign in again. Check that only one client process starts and that the example port is listening again. Closing and reopening the window doesn’t verify login startup. If a client update changes the install path or launch options, update any manually copied desktop file too.

Common issues with permissions, the tray, and relaunching

Follow the same troubleshooting order each time: can the program start, can the core listen, can a request get through, and does autostart work at login? This helps distinguish a hidden window, a port conflict, and a network problem. These four issues are especially common on a first setup.

Updates and rollbacks: keep package management and startup entries in sync

For future updates, install the new package using the same package manager. Back up your configuration in the client first, and keep subscription URLs and node credentials secure; they may grant access and shouldn’t appear in public troubleshooting screenshots. After updating, check the client and core versions, listening port, and autostart entry again.

1. Exit the client and confirm that the process and core have stopped before installing a package for the correct architecture.
2. Launch the client manually, complete one request using an explicitly specified proxy, then log out and back in to verify autostart.
3. If the new version fails, save the specific error and check whether its system runtime requirements have changed. Don’t delete all user configuration as a first step.
4. To roll back, use the version management method supported by your package manager. Check compatibility with older-version settings separately; don’t assume compatibility in both directions.
5. To disable manual login startup, remove the corresponding desktop file from your user’s autostart directory. Uninstalling the system package may not remove a file you copied there yourself.

A successful setup means more than just opening a window: the client starts as a regular user, proxy requests work, only one instance launches at login, and the app’s network state is restored when it exits. Verify each of these four points to quickly narrow down future issues to installation, the core, the proxy entry point, or the desktop session.