At a glance

This guide is for users with a Linux graphical desktop who are ready to install v2rayN. Choose a deb or rpm package for your distribution, verify the executable path and Xray Core, then configure the tray component, local proxy ports 10808 and 10809, and systemd login autostart. Use logs and listening ports to confirm a successful launch.

Check the architecture and desktop session first

The v2rayN Linux desktop app must run inside a graphical session. Debian, Ubuntu, and Linux Mint use deb packages; Fedora, Rocky Linux, and AlmaLinux use rpm packages. The package format must match the distribution, and the processor architecture must match as well. Most PCs use x64; devices with ARM processors use arm64. Do not choose x64 solely because the operating system is 64-bit.

Run the following commands in a terminal first. The first reads the processor architecture, the second shows the distribution identifier, and the third confirms the current desktop session type. Choose an x64 package when the output is x86_64, or an arm64 package when it is aarch64. XDG_SESSION_TYPE usually shows wayland or x11.

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

This guide uses the v2rayN 7.15.2 interface and package workflow as its baseline. Button locations may change slightly in later versions, but the installation commands, user-service directory, and port troubleshooting methods remain the same. Before upgrading, exit any running v2rayN instance so an old process does not keep the configuration file or local listening ports open.

7.15.2
Guide baseline
10808
Common SOCKS port
10809
Common HTTP port
15 seconds
Startup observation window

Choose a deb or rpm installation method

Both deb and rpm are system packages. They install the application, desktop entry, and icons in locations defined by the distribution, then register them with the package manager. Compared with manually extracting an archive, a system package makes files easier to locate and uninstall, and reports missing dependencies during installation.

Native system package

Recommended

Use deb on Debian and Ubuntu, and rpm on Fedora-based distributions. The package manager registers the application entry and desktop files in one place.

Best for: long-term use, menu entries, and version management

Manually extracted archive

Keep the application in a user directory, replace files manually when upgrading, and enter the executable path yourself in the systemd service.

Best for: no system installation privileges or temporary testing

Keep the old version

Export your configuration first, then install the new package over the existing application. Do not run both versions at once, or ports 10808 and 10809 may conflict.

Best for: a short-term fallback before upgrading

Install a deb package on Debian and Ubuntu

Move the downloaded deb file into the “Downloads” directory, enter that directory, and install the local package with apt install. Replace the filename in the command with the actual name; use ls *.deb to check it first. Unlike calling dpkg directly, apt also resolves dependencies available from configured repositories.

cd ~/下载
ls *.deb
sudo apt install ./v2rayN-linux-64.deb

If the system directory name is in English, the path is usually ~/Downloads. If you previously installed the package with dpkg -i and saw unmet dependencies, run sudo apt -f install to repair them, then run the installation command again. When upgrading a package with the same name, apt preserves configuration data in the user directory.

Install an rpm package on Fedora-based distributions

On Fedora, use dnf install for local rpm packages. The ./ before the filename means the file is in the current directory and must not be omitted as if it were a repository package name. After installation, use a case-insensitive query command to verify the package record.

cd ~/Downloads
ls *.rpm
sudo dnf install ./v2rayN-linux-64.rpm
rpm -qa | grep -i '^v2rayn'

Debian / Ubuntu

Package format
deb
Installation command
apt install ./文件名.deb
Dependency repair
apt -f install
Uninstall and query
dpkg -l | grep -i v2rayn

Prefer apt for local packages and repository dependencies.

Fedora-based distributions

Package format
rpm
Installation command
dnf install ./文件名.rpm
Dependency handling
Resolved by dnf
Installation query
rpm -qa | grep -i v2rayn

Keep the ./ path prefix when installing a local file.

First launch and core settings check

After installation, launch v2rayN from the application menu before configuring background autostart. On the first run, confirm that the main window opens, the core starts, and the configuration directory is writable. If the application menu has not refreshed, log out and back into the desktop, or run command -v v2rayN in a terminal to find the launch command.

In the main interface, open “Settings” → “Parameter settings” → “Core type”. Choose Xray when using VLESS, Reality, or newer Xray features; existing VMess nodes can also be handled by Xray. The node protocol, address, port, user ID, transport, TLS, and Reality settings must match the server item by item. A successful client installation does not mean the node settings are correct.

  1. Launch the main application

    Open v2rayN from the desktop application menu and wait for the main window to finish loading. If you launch it from a terminal, keep the terminal output visible so missing components are easy to spot.

  2. Choose the core

    Go to “Settings” → “Parameter settings” → “Core type”. For everyday use with VLESS, Reality, or VMess, select Xray and save the setting.

  3. Import a subscription

    Add the complete subscription URL under “Subscription groups”, save it, and update the subscription. If the update fails, first check the system clock, DNS, and current network connection.

  4. Select a node

    Select a configuration in the node list, set it as the active server, and start the core. Do not run another proxy program that uses the same local ports.

  5. Check the proxy

    Check local SOCKS port 10808 and HTTP port 10809, then enable the system proxy if needed. Use the values shown on the current parameter settings page as the source of truth.

After startup, use ss to check the listening state. If you see 127.0.0.1:10808 or the local address specified on the settings page, the core has created a local entry point. If the main interface says it is running but no listener appears, check the v2rayN log for the core exit reason.

ss -lntp | grep -E '10808|10809'
ps -ef | grep -E 'v2rayN|xray' | grep -v grep

Fix a missing desktop tray icon

After the main window closes, v2rayN usually remains in the system tray, so tray visibility affects exiting, switching nodes, and restoring the window. A missing icon does not necessarily mean the core stopped. First use ps and ss to check the process and ports, then verify that the desktop environment supports status icons.

Ubuntu and some GNOME desktops typically rely on the Ayatana AppIndicator component. Install the runtime first, then log out and back into the desktop. Fedora package names vary by version and enabled repositories, so search with dnf search appindicator instead of mixing deb packages from another distribution.

sudo apt update
sudo apt install libayatana-appindicator3-1

dnf search appindicator

In a Wayland session, if the main window works but the tray menu does not appear, first confirm that the desktop panel allows application status icons. Then fully exit v2rayN and start it again. Repeatedly clicking the application menu may trigger the single-instance restriction: no new window appears even though the old background process is still running.

No main window after clicking the icon?

Run pgrep -a v2rayN to find an old process. If one exists, exit from the tray first. If the tray is not visible, terminate the process, then launch from a terminal and watch the output.

Is the tray icon blank?

Reinstall the AppIndicator runtime, log out of the desktop session, and log back in. Restarting v2rayN alone may not make the desktop panel reload icon support.

Still unable to open webpages after the core starts?

Run ss -lntp to check ports 10808 and 10809, then verify whether the system proxy is set to the SOCKS or HTTP port. Do not swap the protocol and port.

Does subscription updating keep timing out?

Correct the system clock first, then check DNS and make sure the subscription URL is complete. If a usable node is already available, enable proxy-based updates in the subscription settings and try again.

Did your existing nodes disappear after an upgrade?

Confirm that you launched the system-installed version rather than an extracted copy in an old directory. The two applications may read different configuration directories, so exit the old process and check the active configuration path.

Configure a systemd user service

A desktop application should use a systemd user service rather than a system-level root service. The user service runs under the current account’s user manager, can read that account’s configuration directory, and makes logs available through journalctl --user. Here, autostart means launching automatically after the user enters the graphical desktop; v2rayN needs the tray and display session, so it should not be forcibly started while no user is logged in.

Run command -v v2rayN first to get the actual path. A system package commonly returns /usr/bin/v2rayN, but use the result from your own machine. Then create the user-service directory and service file.

command -v v2rayN
mkdir -p ~/.config/systemd/user
nano ~/.config/systemd/user/v2rayn.service

Write the following content to the file. If the first command returns a path other than /usr/bin/v2rayN, update ExecStart accordingly. The service restarts after an abnormal exit with a five-second delay and starts after the graphical session and network targets are available.

[Unit]
Description=v2rayN desktop client
After=graphical-session.target network-online.target

[Service]
Type=simple
ExecStart=/usr/bin/v2rayN
Restart=on-failure
RestartSec=5

[Install]
WantedBy=default.target

Service file

Location
~/.config/systemd/user/v2rayn.service
Service type
Type=simple
Restart policy
on-failure
Delay
5 seconds

The service belongs to the current desktop user; do not use sudo to create it.

Runtime requirements

Executable path
command -v v2rayN
Startup targets
default.target
Session requirement
Graphical desktop logged in
Log scope
systemd user logs

Do not configure the graphical client as a root system service.

After saving, reload the user services, enable the service, and start it immediately. Wait about 15 seconds, then check its status. When the status is active (running) and the local port is present, the autostart chain is working.

systemctl --user daemon-reload
systemctl --user enable --now v2rayn.service
systemctl --user status v2rayn.service
ss -lntp | grep -E '10808|10809'

Log checks, disabling, and post-upgrade maintenance

When the service fails to start, inspect the latest 50 lines of the user log first. Common causes include an incorrect ExecStart path, another v2rayN instance already running, port 10808 being occupied, or the desktop session not being ready. Do not repeatedly reinstall the package without reading the logs; reinstalling will not automatically fix configuration errors or port conflicts.

journalctl --user -u v2rayn.service -n 50 --no-pager
systemctl --user restart v2rayn.service
systemctl --user is-enabled v2rayn.service
systemctl --user is-active v2rayn.service

If the log reports Address already in use, use the following command to identify the process holding the port. After confirming its purpose, exit the conflicting application, or open v2rayN “Settings” → “Parameter settings” and change the local listening port. Update the port in the browser, terminal environment variables, and system proxy settings as well.

ss -lntp | grep ':10808'
lsof -iTCP:10808 -sTCP:LISTEN

When login autostart is temporarily unnecessary, disable and stop the service together. After editing the service file, reload it and restart the service. After upgrading through deb or rpm, run command -v v2rayN again to confirm that the application path has not changed.

systemctl --user disable --now v2rayn.service

systemctl --user daemon-reload
systemctl --user restart v2rayn.service