Install v2rayN on Linux: DEB/RPM Packages and Autostart

1. Linux Distributions and Package Architecture

v2rayN is a desktop client for managing connection profiles, launching proxy cores, and providing a graphical interface. Installing the desktop package does not deploy a background proxy service. This guide assumes you are already in a graphical session such as GNOME or KDE Plasma; its desktop autostart steps are not suitable for a server accessed only through a remote terminal.

Run these two commands first. /etc/os-release identifies the distribution, and uname -m reports the machine architecture. Don’t choose an x64 package just because the device is described as “64-bit”; ARM64 is also a 64-bit architecture.

cat /etc/os-release
uname -m

In the Linux section of the download page, choose the package that matches your system: select x64 for an x86_64 machine or ARM64 for an aarch64 machine. The steps below cover standard writable systems. For distributions with an immutable root filesystem, use that system’s deployment method; don’t assume a host-level dnf install workflow is available.

2. Install Local DEB and RPM Packages

Download the package from the client download page. Keep its original filename to avoid mixing up packages for different architectures. The commands below prompt you for the local file path; use Bash Tab completion if helpful. Enter the path as-is, without adding quotes. Run each set of commands in order in the same terminal session.

Debian / Ubuntu: Install a DEB with apt

read -r -e -p 'DEB file path: ' package
package=$(realpath -- "$package")
dpkg-deb --field "$package" Package Version Architecture
sudo apt update
sudo apt install "$package"

First, dpkg-deb displays the package name, version, and architecture so you can check them before installing. The argument passed to apt is an absolute local path, not a package name from a repository. apt can resolve dependencies from enabled repositories, but it can’t provide library versions that aren’t available for your release.

Fedora: Install an RPM with dnf

read -r -e -p 'RPM file path: ' package
package=$(realpath -- "$package")
rpm -qp --queryformat '%{NAME} %{VERSION}-%{RELEASE} %{ARCH}\n' "$package"
sudo dnf install "$package"

rpm -qp queries the package file; it does not install the program. Use dnf for the actual installation so it can resolve dependencies and record the transaction. If prompted about a signature or source, verify where the package came from and review its details. Don’t disable checks just to proceed.

3. First Launch and Local Proxy Checks

Once installation is complete, search for v2rayN in your desktop application menu and launch it. Open the interface as a regular user; don’t run the entire desktop application with sudo. Running it as an administrator may create configuration files owned by root and mix desktop-session permissions with network permissions.

1. Launch the client

   Search for v2rayN in the application menu. If it isn’t listed, first check that installation completed, then use the next section to locate the actual .desktop file. Don’t guess the executable path.

2. Import a connection

   Copy an existing connection share link, then use the import-from-clipboard command in the main window’s “Server” menu. Menu wording may vary between versions; check that the imported entry has the expected server address and port.

3. Select a server

   Select the desired entry in the server list, then choose “Set as active server” from its context menu. Check the logs for configuration errors or port conflicts before continuing.

4. Check the listening port

   In “Settings” → “Parameter settings,” check the local listening port and proxy protocol against the core startup log. The example below uses port 10808; run it only if a SOCKS endpoint is actually listening on that port.

First test the route that explicitly specifies a proxy in the terminal, then check the desktop system proxy. This separates server connectivity issues from desktop environment settings. The three numbers below are fixed diagnostic command parameters, not speed-test results or defaults for every version.

ss -lntp 'sport = :10808'
curl --proxy socks5h://127.0.0.1:10808 \
  --head --max-time 15 https://v2rayguanwang.com/

socks5h sends the destination hostname to the SOCKS proxy for resolution. If you get Connection refused, check the local listener first. If the proxy connection succeeds but TLS or the remote request times out, check the node settings, system time, and outbound network. An HTTP response confirms only that this request received a response; it does not mean every application is using the proxy.

4. Desktop Autostart: Launch v2rayN at Login

What desktop users often call “startup on boot” usually means launching the client after signing in to the graphical desktop. The XDG autostart directory, ~/.config/autostart/, is designed for this purpose. It won’t run when the machine starts before anyone logs in, and it can’t keep a separate system service running after you log out.

First, try adding the app through your desktop environment’s startup applications settings. If you need to configure autostart manually, reuse the desktop entry installed by the package. It usually contains the correct Exec, icon, and launch arguments, making it more reliable than guessing a path under /opt/.

find /usr/share/applications "$HOME/.local/share/applications" \
  -maxdepth 1 -type f -iname '*v2rayn*.desktop' -print 2>/dev/null

If there’s no output, inspect the package file list: for a DEB, use dpkg-deb --contents "$package"; for an RPM, use rpm -qpl "$package". Here, package is the package path read earlier. If you’ve opened a new terminal, read the variable again. Once you find the installed desktop entry, continue with the copy command below.

read -r -e -p 'Installed desktop file path: ' desktop
if test -f "$desktop"; then
  install -Dm644 -- "$desktop" "$HOME/.config/autostart/v2rayn.desktop"
  grep -E '^(Type|Name|Exec|TryExec|Hidden|OnlyShowIn|NotShowIn|X-GNOME-Autostart-enabled)=' \
    "$HOME/.config/autostart/v2rayn.desktop"
else
  printf '%s\n' 'File not found. Check the desktop entry path and try again.'
fi

• Check the launch target: Exec should point to the installed program. If TryExec is present, that command must also exist. Keep the original file’s arguments and escaping rules.
• Check for disable flags: If you see Hidden=true, change it to Hidden=false in a text editor. In GNOME, also check whether X-GNOME-Autostart-enabled=false is present and enable the entry if needed.
• Check desktop restrictions: OnlyShowIn and NotShowIn can limit which desktop environments use the entry. Change them only after confirming what they do; don’t delete every field indiscriminately.
• Check for duplicate entries: Keep just one active autostart configuration, whether it’s the client’s own setting, the desktop startup manager, or a manually created file. Otherwise, multiple instances may launch.

After saving, exit the client normally, then log out and back in. Don’t assume the process has exited just because you closed the window; some settings minimize it to the tray. After signing in again, check the interface, core logs, and listening port separately. A tray icon alone doesn’t prove the proxy is working.

5. Verify Autostart, Upgrade, and Roll Back

Test autostart across both the desktop and network startup stages. The desktop may load before Wi-Fi, name resolution, or the remote connection is ready. A timeout logged right after startup doesn’t necessarily mean installation failed. Once the network is available, retry an explicitly configured proxy request.

Before upgrading, export your connection settings using the client’s available export feature. Note the local listening port, routing mode, and core in use. To back up the configuration directory, confirm its actual location in the current client interface or logs rather than assuming a path from another operating system applies to Linux. Configuration may contain connection credentials, so restrict access to backup files.

Download the new package and install it with the same package manager. Exit the client before upgrading so an old process doesn’t lead you to misidentify the version. A manually copied autostart file won’t update automatically when the desktop entry changes. If the Exec path changes after an upgrade, copy the updated entry and check its disable flags again. An older version may not be able to read configuration written by a newer one, so keep the relevant backup before rolling back.

6. Dependencies, Desktop Sessions, and Proxy Troubleshooting

When troubleshooting, note the distribution name, uname -m output, package version, desktop environment, and first clear error. Remove subscription URLs, connection identifiers, and server credentials before sharing logs. Installation, launch, listening, and application proxy use are four separate stages. Checking them in order is more effective than repeatedly reinstalling.