Install v2rayN on Linux: DEB and RPM Packages, Autostart Setup

Install v2rayN on Debian, Ubuntu, Fedora, or openSUSE. Learn to resolve dependencies, find the desktop launcher, and start v2rayN at login with XDG autostart.

At a glance

This guide is for anyone installing v2rayN on a Linux desktop. Choose a package based on your distribution and CPU architecture, install it with your package manager, then launch v2rayN from the desktop menu as a regular user. After confirming it starts manually, reuse the package's desktop launcher to start it at login, then verify both the client process and proxy traffic.

Choose a package: identify your distribution and CPU architecture

Run these two commands on the system where you plan to use v2rayN. The first prints your distribution ID; the second shows your system architecture. If you're using a virtual machine, run them inside the VM—don't choose a package based on the host machine.

cat /etc/os-release
uname -m

Debian / Ubuntu

Package
.deb
Package manager
apt
Check architecture
dpkg --print-architecture

In package metadata, amd64 corresponds to x86_64, and arm64 to aarch64.

Fedora / openSUSE

Package
.rpm
Package manager
Use dnf on Fedora and zypper on openSUSE
Architecture
x86_64 or aarch64

The same file extension doesn't guarantee the same dependencies. Check the release notes for supported distributions and versions.

64-bit
x86_64 architecture width
10808
Common local ports; check the client for the actual value

Install a DEB or RPM package with dependency handling

In a terminal, go to the directory containing the package. ./v2rayN.deb and ./v2rayN.rpm below are example local filenames; replace them with the actual filenames when you run the command. Keep the ./ prefix to tell the package manager to install a file from the current directory. Choose only the command that matches your distribution.

# Debian / Ubuntu
sudo apt install ./v2rayN.deb

# Fedora
sudo dnf install ./v2rayN.rpm

# openSUSE
sudo zypper install ./v2rayN.rpm

Distribution package manager

Recommended

Reads dependencies from the local package and finds compatible versions in enabled repositories. Review which packages will be added, upgraded, or removed before confirming.

Best for: first-time installs and upgrades

Low-level package tools

Inspect package metadata or dependencies with dpkg-deb -I ./v2rayN.deb or rpm -qpR ./v2rayN.rpm. Unlike the package managers above, installing with a low-level tool won't fetch missing dependencies from repositories.

Best for: inspecting package declarations and tracking down missing dependencies

If Debian or Ubuntu reports missing dependencies, run sudo apt update first, then retry the install command. If a library version doesn't meet the requirement, note the library name and minimum version in the error, then check whether your distribution release is supported. Don't force the installation by ignoring dependencies. If dpkg left packages unconfigured, review the transaction summary before running sudo apt --fix-broken install: if the repositories can't satisfy the dependencies, the proposed fix may remove the package instead of installing it.

Launch from the desktop menu: find the app and troubleshoot startup

  1. Search for the app

    After installation, search for “v2rayN” in GNOME's app search or KDE Plasma's application launcher. Launch it once as your regular desktop user. Installation commands require administrator privileges; launching the graphical client does not.

  2. Inspect the package file list

    If the app doesn't appear in the menu, use dpkg-query -L with the installed package name on Debian-based systems, or rpm -ql with the installed package name on RPM-based systems. Find the package name with dpkg-deb -f ./v2rayN.deb Package or rpm -qp --qf '%{NAME}\n' ./v2rayN.rpm. Look for a .desktop file in the listing—that's the launcher to check next. The package filename is not a command for starting the app.

  3. Check the launcher fields

    Open the desktop launcher file and check Name and Exec. If it contains NoDisplay=true, the launcher may exist without appearing in the app menu. If it contains TryExec, make sure the referenced program exists and is executable. Don't edit launchers in system directories; package upgrades may overwrite your changes.

  4. Check startup output

    If the icon appears but clicking it opens no window, first check whether an instance is already running in the system tray. Then, from a terminal in the graphical session, run the program referenced by the launcher as a regular user. Keep any required arguments, but don't pass desktop-entry field codes such as %U or %F to the program. Note the first startup error and determine whether it's a missing library, an invalid path, or an already-running client.

XDG autostart: launch v2rayN when you log in

XDG autostart is handled by the graphical desktop session. It runs after you log in; it does not start a system service at boot before login. First check whether the client already has autostart enabled or v2rayN is already listed in your desktop's startup applications. Keep just one launcher per account to avoid duplicate startup attempts.

  1. Run the command below to create an autostart directory for your user. If XDG_CONFIG_HOME is set, use its autostart subdirectory; the usual location is ~/.config/autostart.
  2. In your file manager, copy the .desktop file you found in the previous section into that directory. Keep its actual filename and original Exec value. Don't copy the package file, and don't use sudo to create a per-user launcher.
  3. Open the copy in a text editor and check the [Desktop Entry] section. If it contains Hidden=true, remove the line or change it to Hidden=false. Make sure OnlyShowIn and NotShowIn allow your current desktop session, and that TryExec still points to a valid program.
  4. Log out of your graphical session, then log back in. Check for the window, system tray icon, or process in your system monitor. If you see a process but no window, check whether launch-minimized is enabled before treating it as a startup failure.
autostart_dir="${XDG_CONFIG_HOME:-$HOME/.config}/autostart"
mkdir -p "$autostart_dir"
printf '%s\n' "$autostart_dir"

To disable the autostart entry you added, delete only the copy in your user directory and keep the original in the system directory. If your desktop has a system-wide autostart entry with the same name, deleting the user copy may let the system entry take effect again. In that case, disable it in your desktop's startup settings or override it with a same-named user entry containing Hidden=true. After a package upgrade, check whether the system launcher's Exec value has changed and update your user copy if needed.

Troubleshoot after login: check the app, ports, and proxy settings separately

It launches from the menu, so why doesn't it start after login?

First, check the autostart directory printed in the terminal and make sure you copied the actual .desktop file—not a copy your text editor renamed with a .txt extension. Then check launcher restrictions and the executable path. If the launcher also fails when run manually, fix the startup error instead of masking it with a delay.

The process is running, so why isn't my browser using the proxy?

In v2rayN, open “Settings” → “Parameter Settings” and check the local listening port. Then check whether “System Proxy” in the tray menu is set or cleared. Use ss -ltnp to inspect TCP listeners and look up the port shown by the client. A listening port only confirms that a local process accepts connections; also check the browser's proxy source, the active node, and the client logs.

Subscriptions didn't update after login—is autostart broken?

First make sure the client has started, then wait for the network to come online and try updating the subscription manually. If that works, check whether Wi-Fi was connected when you logged in and review the client's subscription update settings. Starting the desktop app, getting a network connection, and updating subscriptions are separate steps—verify each one independently.

Download v2rayN