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
dnfon Fedora andzypperon openSUSE - Architecture
x86_64oraarch64
The same file extension doesn't guarantee the same dependencies. Check the release notes for supported distributions and versions.
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
RecommendedReads 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
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.
Inspect the package file list
If the app doesn't appear in the menu, use
dpkg-query -Lwith the installed package name on Debian-based systems, orrpm -qlwith the installed package name on RPM-based systems. Find the package name withdpkg-deb -f ./v2rayN.deb Packageorrpm -qp --qf '%{NAME}\n' ./v2rayN.rpm. Look for a.desktopfile in the listing—that's the launcher to check next. The package filename is not a command for starting the app.Check the launcher fields
Open the desktop launcher file and check
NameandExec. If it containsNoDisplay=true, the launcher may exist without appearing in the app menu. If it containsTryExec, make sure the referenced program exists and is executable. Don't edit launchers in system directories; package upgrades may overwrite your changes.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
%Uor%Fto 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.
- Run the command below to create an autostart directory for your user. If
XDG_CONFIG_HOMEis set, use itsautostartsubdirectory; the usual location is~/.config/autostart. - In your file manager, copy the
.desktopfile you found in the previous section into that directory. Keep its actual filename and originalExecvalue. Don't copy the package file, and don't usesudoto create a per-user launcher. - Open the copy in a text editor and check the
[Desktop Entry]section. If it containsHidden=true, remove the line or change it toHidden=false. Make sureOnlyShowInandNotShowInallow your current desktop session, and thatTryExecstill points to a valid program. - 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.