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
Check package metadata
From the package's directory, inspect a DEB with
dpkg-deb -f filename.deb Package Version Architecture Depends, or an RPM withrpm -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.Install the local package
On Debian or Ubuntu, run
sudo apt update, thensudo apt install ./filename.deb. On Fedora, usesudo dnf install ./filename.rpm; on openSUSE, usesudo 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.Check dependencies
If the installer reports missing dependencies, note the missing package or library names and any required minimum versions. For APT, check the
Dependsfield; for RPM, view declared requirements withrpm -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.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
RecommendedUse 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.
- Run
mkdir -p "${XDG_CONFIG_HOME:-$HOME/.config}/autostart". Copy the verified.desktopfile from the previous step into that directory. You do not needsudoor a system-level service for a desktop client. - Check that
ExecandTryExecin the copy still point to the current installation. If it containsHidden=true,OnlyShowIn, orNotShowIn, check that these fields do not disable the entry or exclude your desktop environment. IfExecincludes file or URL field codes, use the verified plain launch command in the autostart copy, without passing a file or URL. - 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, runss -ltn 'sport = :10808'to check for a listener. If the port is in use, tryss -ltnp 'sport = :10808'to identify the process. - 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.