Install v2rayN on Linux: DEB/RPM Packages and Autostart

At a glance

First, check your Linux distribution and CPU architecture, then install the local package with apt or dnf. After installation, launch v2rayN from the applications menu and verify the local listener and server connection. Finally, add the installed desktop entry to autostart for your user account. This guide is for Linux computers with a graphical desktop; it does not configure the GUI client as a system-wide background service.

Check your distribution, architecture, and desktop environment

If you see an “incompatible package architecture” error or double-clicking the installer does nothing, don’t change your kernel. DEB and RPM are package formats used by Linux distributions, not proxy protocols. Ubuntu and Debian use DEB; Fedora uses RPM. v2rayN is a graphical client that manages servers, generates configuration, and launches the core. Its Linux desktop package is not a service package for a headless server.

cat /etc/os-release
uname -m
printf 'Desktop: %s\nSession: %s\n' "$XDG_CURRENT_DESKTOP" "$XDG_SESSION_TYPE"

If uname -m outputs x86_64, choose the x64 package; if it outputs aarch64, choose the ARM64 package. Debian packages often label these architectures amd64 and arm64; the names differ, but the architectures are the same. Don’t bypass architecture checks by extracting the package or forcing installation.

Native Linux packages

Recommended

Choose DEB for Ubuntu or Debian and RPM for Fedora. The package manager registers the files, resolves dependencies, and lets you find the desktop entry in the installed file list.

Best for: Desktop users who want to launch from the applications menu and keep upgrade and uninstall records.

Linux archive

Consider this only if the download page offers an archive for your architecture. You’ll need to preserve the directory structure, set executable permissions, and create a desktop entry yourself. The package-query commands below don’t apply.

Best for: Users experienced with manual installations, or whose system cannot use the available package.

Go to the client downloads page and choose the Linux package. The steps below don’t assume a particular release or filename; they read the metadata from the file you actually downloaded, so an outdated version number from an old guide won’t be mistaken for the current release.

Install a DEB package on Ubuntu or Debian with apt

Use a Bash terminal. The commands below prompt for the package’s full path, then display its name, version, and architecture. Enter the path without extra quotes or backslash-escaped spaces; the command handles quoting. Install only after confirming the file’s source and metadata.

read -r -e -p "Full path to the DEB file: " package
package="$(realpath -- "$package")"
dpkg-deb -f "$package" Package Version Architecture
pkg_name="$(dpkg-deb -f "$package" Package)"

sudo apt update
sudo apt install "$package"

When apt install receives the absolute path to a local package, it can fetch available dependencies from your configured repositories. Don’t run only dpkg -i and assume installation is complete: it can register the package, but won’t automatically download missing dependencies. Check the installation status after the install command finishes successfully.

dpkg-query -W -f='${Package} ${Version} ${Status}\n' "$pkg_name"
dpkg -L "$pkg_name" | grep '/applications/.*\.desktop$'

Check package details
Check the version and Architecture in the output. Keep a note of these details; they’re more useful than saying “I installed the latest version” when troubleshooting an upgrade.
Install dependencies
Wait for apt to finish successfully. If a repository is unreachable, fix your network or repository configuration rather than repeatedly double-clicking the package.
Find the desktop entry
Search for v2rayN in the applications menu. If the menu hasn’t refreshed, log out and back in; there’s no need to reinstall.
Launch as a regular user
Launch the client from the desktop entry. Installation requires administrator privileges, but that doesn’t mean you should run the client with sudo for everyday use.

Install an RPM package on Fedora with dnf

On Fedora, check the package metadata first, then let the package manager install it. Choose either the commands below or the DEB steps—not both formats on the same computer. Keep this terminal open; the desktop-entry lookup later uses the pkg_name variable.

read -r -e -p "Full path to the RPM file: " package
package="$(realpath -- "$package")"
rpm -qpi "$package"
pkg_name="$(rpm -qp --queryformat '%{NAME}' "$package")"

sudo dnf install "$package"
rpm -q "$pkg_name"
rpm -ql "$pkg_name" | grep '/applications/.*\.desktop$'

dnf install resolves dependencies using your enabled repositories. If a shared library is missing or a version constraint can’t be met, save the full error and check whether the package supports your Fedora release. Don’t skip dependency checks and defer the problem until launch, or download a same-named shared library from an unfamiliar source to overwrite a system file.

If the app won’t open, troubleshoot based on the error

“Installed, but no window” doesn’t necessarily mean a dependency is missing. The window may be minimized to the tray, or the app may have exited during startup. Check the tray and process first, then read the launch command from the desktop file provided by the package. Don’t guess the executable’s capitalization or installation path.

Symptom	Check first	What to do
Architecture mismatch	Compare the system’s uname output with the package metadata	Choose the x64 or ARM64 package that matches; don’t force installation.
DEB dependencies not installed	Check apt’s full error and repository status	Run apt --fix-broken install, review the proposed changes, then confirm.
Missing shared library	Get the full name of the missing library from the terminal	Find the corresponding package in your distribution’s repositories and check compatibility with your system version.
No entry in the applications menu	Check whether the installed files include a .desktop file	Check the package contents and menu cache; log out and back in if needed.
App exits immediately after launch	Check the Exec command output and directory write permissions	Troubleshoot the specific error; don’t delete all your configuration first.

On Debian, sudo apt --fix-broken install may propose installing missing dependencies or removing packages that can’t be configured. Review the proposed changes before confirming. If you’ve ever launched the GUI client with sudo, check the ownership of its actual configuration directory. Fix only the application directory you’ve confirmed is affected; don’t recursively change permissions across your home directory.

The Exec= line in a desktop file defines a launch rule; it isn’t a script you can blindly paste into a terminal. If it contains desktop field codes such as %U or %F, remove those codes when testing manually, while keeping the actual command, arguments, and path quoting. Don’t use eval to execute the entire line you’ve read.

Verify the listener and proxy before configuring autostart

When you first open v2rayN, import a working configuration and select a server. To add a subscription, open “Subscription Group” → “Subscription Group Settings” in the main window and enter the group and URL. Then use the “Subscription Group” menu to run the appropriate update. Button placement may vary between versions, so follow the labels in your current interface. A successful subscription update means the server information was retrieved—not that a server is reachable.

Go to “Settings” → “Parameter Settings” and check the local listener options. This guide uses 127.0.0.1:10808 as an example mixed-proxy address; your setting must match the client. Don’t change an existing port just because this guide uses 10808, and don’t bind to all network interfaces to fix a local connection issue.

10808

Example local proxy port

127.0.0.1

Loopback address

15 seconds

Request timeout below

ss -ltnp 'sport = :10808'
curl --proxy http://127.0.0.1:10808 --max-time 15 -I https://example.com/
curl --proxy socks5h://127.0.0.1:10808 --max-time 15 -I https://example.com/

These requests are useful only if a listener for the relevant protocol is enabled. socks5h lets the proxy resolve the destination hostname, making it possible to distinguish that path from local DNS resolution. An HTTP response confirms only that this request completed; it doesn’t prove that all sites or applications are going through the proxy. If the logs show a direct connection, choose a test destination that matches your routing rules.

Test the explicit proxy

Proxy address: 127.0.0.1
Example port: 10808
Request method: curl --proxy
Timeout: 15 seconds

Bypass desktop proxy settings first to verify the client listener and outbound connection.

Check the desktop proxy

GNOME settings path: “Settings” → “Network” → “Network Proxy”
Check: HTTP, HTTPS, and SOCKS addresses and ports
Browser settings: Browser extensions and the browser’s own proxy settings
Terminal settings: http_proxy、https_proxy、all_proxy

Desktop proxy settings don’t automatically apply to every terminal app. Check each layer with the same test address.

Configure autostart at desktop login

What desktop users call “startup at boot” should usually mean launching after the current user signs in to the graphical session. By then, the desktop session, user configuration, and tray environment are ready. Don’t create a system service running as root to launch a windowed app; this can cause display server, session bus, and file ownership issues.

Choose one autostart method to avoid duplicate launches

Built-in client option

Check “Settings” → “Parameter Settings” for a “Launch at startup” option.
Enable it only if it’s available and works in your current Linux version.
After enabling it, test by logging out and back in. Don’t also copy the desktop entry.

XDG login autostart

Use the .desktop file provided by the installed package.
Copy it to the current user’s ~/.config/autostart/.
For desktop sessions that follow the XDG autostart specification.

Choose one method. If your environment has only a window manager and no full desktop session, check how that session handles startup.

For the XDG method, find the desktop file first. Choose one of the two package-query commands below based on your distribution. If you’ve closed the installation terminal, confirm the package’s actual name with the package manager and set pkg_name again; don’t assume the old variable still exists.

# Ubuntu / Debian
dpkg -L "$pkg_name" | grep '/applications/.*\.desktop$'

# Fedora
rpm -ql "$pkg_name" | grep '/applications/.*\.desktop$'

If several entries are listed, choose the one that launches the main interface—not an uninstaller or helper. Enter its full path, check the key fields, then copy the original file. This preserves the package’s Exec, Icon, and working-directory settings, so there’s no need to guess where the program is installed.

read -r -e -p "Full path to the main interface desktop file: " desktop
desktop="$(realpath -- "$desktop")"
grep -E '^(Type|Name|Exec|TryExec|Path|Hidden|OnlyShowIn|NotShowIn|X-GNOME-Autostart-enabled)=' "$desktop"

mkdir -p "$HOME/.config/autostart"
install -m 644 "$desktop" "$HOME/.config/autostart/v2rayn.desktop"

Before copying, confirm the entry has Type=Application and doesn’t contain Hidden=true or a field that disables autostart. If it has OnlyShowIn or NotShowIn, check that the current desktop isn’t excluded. If you encounter these restrictions, check what they’re for and edit your user copy; don’t modify the original file managed by the package manager.

Retest after login, upgrade, or undo the setup

After configuring autostart, exit the client normally, then log out and back in. Don’t assume the process has ended just because you closed the window; some settings minimize it to the tray instead. After logging back in, check the process, listening port, and request result. The setup is complete only when all three pass.

Make sure only one instance launches: Check the desktop’s Startup Applications, the client’s built-in option, and the user’s autostart directory. Remove any duplicate entries.
Make sure your configuration is accessible: Your server list, subscription groups, and selected server should still be there. You shouldn’t be using a separate configuration created by launching as an administrator.
Make sure the network is ready: A subscription update may fail if Wi-Fi hasn’t connected yet after login. Wait for the network, then retry manually; that alone doesn’t mean autostart is broken.
Make sure the proxy is working again: Repeat the port and curl tests, then check the browser. Seeing the window doesn’t mean the system proxy settings are active.

Before upgrading, exit the client, then install a package for the same architecture using the same package manager. A desktop file copied to your user directory won’t update when the original changes. If the new release changes Exec or the installation path, review and copy the entry again. Back up the data directory the client actually uses before migrating; don’t store backups in the installation directory, where an update could overwrite them.

To undo the XDG autostart setup in this guide, delete only the user copy you created. If you used the client’s built-in option, turn it off in the same settings location. Before uninstalling, remove any desktop proxy settings you no longer use; otherwise, your browser may keep trying to connect to a port that is no longer listening.

rm -f "$HOME/.config/autostart/v2rayn.desktop"

Keep the troubleshooting order consistent: confirm the package installed correctly, check that the main program launches, verify the local port and server connection, then check desktop proxy settings and login autostart. Testing each layer separately makes it easier to find the cause than changing dependencies, ports, permissions, and startup settings all at once.