Install v2rayN on Linux: DEB/RPM Packages and Autostart

Install v2rayN on Debian, Ubuntu, Fedora, or openSUSE. Set up dependencies, desktop shortcuts, and launch on login.

At a glance

For users installing or migrating v2rayN on a Linux desktop. First check your distribution, package architecture, and dependencies. Then verify that the app launches from the applications menu before reusing its desktop entry for autostart. Autostart runs after you sign in to the desktop; it does not start a system service before the login screen.

Choose DEB or RPM: check your distribution and architecture

Run cat /etc/os-release to identify your distribution and version, then uname -m to check your machine architecture. On Debian-based systems, use dpkg --print-architecture to confirm the architecture name used by the package manager. On RPM-based systems, check with rpm --eval '%{_arch}'. x64, amd64, and x86_64 in filenames often refer to the same class of machine, but package metadata determines compatibility.

Debian / Ubuntu

Package format
.deb
64-bit x86 package architecture
amd64
64-bit ARM package architecture
arm64
Install locally
apt install ./filename.deb

APT installs the local package and resolves dependencies from your enabled repositories.

Fedora / openSUSE

Package format
.rpm
64-bit x86 package architecture
x86_64
64-bit ARM package architecture
aarch64
Install locally
Use DNF on Fedora and Zypper on openSUSE

RPM format alone does not guarantee compatible dependencies. Check the target distribution and version.

A matching architecture name does not guarantee that a build is available for your release. If the download page has no compatible package, do not change the file extension or force an architecture override. If an archive is available for your release, follow its build instructions and install it in a stable location under your user directory. Do not point the desktop entry you create later to a temporary extraction directory.

Install with the package manager and resolve dependencies

  1. Check package metadata

    From the package's directory, inspect a DEB with dpkg-deb -f filename.deb Package Version Architecture Depends, or an RPM with rpm -qp --qf '%{NAME} %{VERSION}-%{RELEASE} %{ARCH}\n' filename.rpm. Replace the filename in the command with the actual downloaded filename. Note the package name: it may differ from v2rayN as shown in the applications menu, and you will need it to look up installed files.

  2. Install the local package

    On Debian or Ubuntu, run sudo apt update, then sudo apt install ./filename.deb. On Fedora, use sudo dnf install ./filename.rpm; on openSUSE, use sudo zypper install ./filename.rpm. Keep ./ so the package manager treats the argument as a local path. If the filename contains spaces, enclose the full path in quotes.

  3. Check dependencies

    If the installer reports missing dependencies, note the missing package or library names and any required minimum versions. For APT, check the Depends field; for RPM, view declared requirements with rpm -qpR filename.rpm. First check whether your distribution's repositories provide them, then decide whether you need a different build. Do not mix repositories from different distributions or install while ignoring dependency errors.

  4. Launch the app manually

    Search for v2rayN in the current user's applications menu. Confirm that the window opens and that you can launch it again after quitting, then configure your subscription and system proxy. Administrator privileges are for installing system packages; run the client as your desktop user to avoid placing configuration files in the administrator's home directory or creating files your account cannot write to.

Applications menu, desktop shortcuts, and launch commands

Some packages register a .desktop file. Use the package name you noted earlier with dpkg -L package-name or rpm -ql package-name, then look for a .desktop file in the output. Check its Name, Exec, and any existing TryExec fields. Do not guess the launch command from the filename. Some desktop environments hide tray icons, so check the window, process, or logs to confirm that the app is running.

Reuse the package's desktop entry

Recommended

Use the existing applications menu entry whenever possible. To keep it easily accessible, use your desktop environment's pin-to-taskbar or add-to-favorites option; the package will continue to manage the executable path.

Best for: DEB or RPM installations that launch successfully from the applications menu.

Create a per-user desktop entry

Create v2rayn-local.desktop in ${XDG_DATA_HOME:-$HOME/.local/share}/applications. Add [Desktop Entry], Type=Application, Name=v2rayN, and Terminal=false, and set Exec to the verified executable path. Enclose executable paths containing spaces in double quotes. Do not use ~ or $HOME; desktop entries do not expand them like an interactive shell does.

Best for: archive installs or builds that do not include an applications menu entry.

To add an icon to the desktop, first run xdg-user-dir DESKTOP to find the current user's desktop directory; do not assume it is named Desktop. Copy the verified entry there only if your desktop environment supports desktop icons and the command returns the actual desktop directory. Then allow launching if prompted. Some desktops hide desktop files by default; in that case, the applications menu entry is enough.

Set up autostart on login and verify proxy status

Use only one autostart method. If this build offers a working launch-on-login option under Settings → Parameter Settings, enable it and verify after signing out and back in. Otherwise, use the XDG autostart directory supported by your desktop environment. The paths below distinguish the desktop entry, autostart entry, and local listener; they serve different purposes.

10808
Example local listening port; check Parameter Settings for the actual value
1
Autostart entries to keep for one client
  1. Run mkdir -p "${XDG_CONFIG_HOME:-$HOME/.config}/autostart". Copy the verified .desktop file from the previous step into that directory. You do not need sudo or a system-level service for a desktop client.
  2. Check that Exec and TryExec in the copy still point to the current installation. If it contains Hidden=true, OnlyShowIn, or NotShowIn, check that these fields do not disable the entry or exclude your desktop environment. If Exec includes file or URL field codes, use the verified plain launch command in the autostart copy, without passing a file or URL.
  3. Quit the client, then sign out and back in to the same desktop account. Do not open it manually first; check whether it has already started. Then go to Settings → Parameter Settings and check the local listening port. If it is set to 10808, run ss -ltn 'sport = :10808' to check for a listener. If the port is in use, try ss -ltnp 'sport = :10808' to identify the process.
  4. Finally, check the system proxy settings and whether the target app uses them. A listening port only means a process is accepting local connections; it does not confirm that your browser is using the proxy or that routing rules select the expected outbound. Test with the node and app that worked manually, and avoid changing your subscription, port, and routing at the same time.

Common Linux installation issues

The local package won't install because a dependency version is too old. What should I do?

Check the build target against cat /etc/os-release. On Debian-based systems, run apt-cache policy package-name to see the candidate version. If your distribution's repositories do not provide the required version, use a build for your distribution or upgrade the distribution through its normal process. Replacing system libraries can affect other programs that depend on them.

It launches from the menu but not after signing out and back in?

Check the effective value of XDG_CONFIG_HOME and make sure the entry is in that account's autostart directory, not just applications. Check the paths and desktop restrictions in the autostart copy. If a custom command relies on environment variables set by a terminal startup script, use the package's desktop entry or a command that runs independently in the desktop session.

Does it start twice after login, or fail to launch after an upgrade?

Check your desktop environment's autostart list and the user's autostart directory to avoid registering both the client's built-in option and a manual entry. After an upgrade, check the desktop entry included in the package. If your manual copy still points to the old location, replace it with the newly verified entry. To disable manual autostart, remove only the copy in the autostart directory and keep the applications menu entry.

Download v2rayN