v2rayN Linux Desktop Installation: deb/rpm Packages and Automatic Startup

Check the Package and System Architecture

The first step when installing on Linux is not double-clicking the file, but confirming the distribution's package format and processor architecture. Ubuntu, Debian, Linux Mint, and other Debian-based distributions use deb packages; Fedora, Rocky Linux, and other RPM-based distributions use rpm packages. If the format is wrong, the graphical software center will usually report that the package cannot be installed or is unsupported.

The processor architecture must match as well. On most desktop computers, uname -m returns x86_64, which corresponds to x64 or 64 in the download options. Some ARM desktop devices return aarch64, which corresponds to arm64. Do not guess the architecture from the system name, and do not use an Android package on a Linux desktop.

You can also run cat /etc/os-release to see the distribution name and version. When connecting to multiple hosts remotely, this command is more reliable than judging by the desktop appearance. v2rayN is a desktop client, so the autostart setup in this guide assumes a regular user with an active graphical session; do not configure the graphical application as a root-level system service.

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

Local deb and rpm Installation

After downloading, install the package through the system package manager from a terminal instead of using the low-level dpkg -i or rpm -i commands directly. APT and DNF read the package's dependency declarations and obtain missing shared libraries from the currently enabled repositories. Run the installation command from the directory containing the package, and make sure the wildcard matches only one v2rayN package.

1. Confirm the architecture

   Run uname -m. If it returns x86_64, choose the x64 package; if it returns aarch64, choose the arm64 package.

2. Choose the package format

   Choose deb for Ubuntu and Debian, and rpm for Fedora. Download the package only from the Linux section of this site's client page.

3. Install the package

   From the download directory, run sudo apt install ./v2rayN-linux-*.deb, or on Fedora run sudo dnf install ./v2rayN-linux-*.rpm.

4. Locate the executable

   Run command -v v2rayN and note the actual executable path. A common result is /usr/bin/v2rayN.

5. Complete the first launch

   Launch v2rayN from the application menu, then open “Settings” → “Parameter settings” → “Core type”. Confirm that the Xray core is selected and save the changes.

The recommended command for Ubuntu and Debian is sudo apt install ./v2rayN-linux-*.deb. The ./ in the command means the local file in the current directory; without it, APT treats the name as a repository package to look up. If running dpkg -i earlier left dependencies unconfigured, run sudo apt --fix-broken install to repair them, then run the local installation command again.

On Fedora, use sudo dnf install ./v2rayN-linux-*.rpm. DNF 5 lists the packages to be added, the download size, and the installation result. If strict repository policies are enabled, run sudo dnf makecache to refresh metadata before trying again; do not bypass dependencies by forcing data into the rpm database.

cd "$HOME/Downloads"

# Ubuntu / Debian
sudo apt update
sudo apt install ./v2rayN-linux-*.deb

# Fedora
sudo dnf makecache
sudo dnf install ./v2rayN-linux-*.rpm

# Verify after installation
command -v v2rayN
v2rayN --version

First Launch, Subscriptions, and Core Listening

A successfully opened window only means that the graphical interface can run; it does not mean the proxy path is ready. At minimum, four conditions must be met: the subscription is updated, a node is selected, the Xray core process is running, and desktop application traffic is entering the local listening port. Follow this order during initial setup to avoid mistaking a disabled system proxy for an unavailable node.

After adding a subscription on the v2rayN main screen, update the current subscription group, then select and start a node. Parameters for protocols such as VLESS and VMess are normally imported from the subscription. Manually changing the address, port, UUID, transport, or TLS settings can make the configuration inconsistent with the server. A subscription only distributes configuration; the client does not provide node addresses.

The common local SOCKS listening port in v2rayN is 10808, and the HTTP listening port is 10809. Use the local listening settings under “Settings” → “Parameter settings” as the source of truth, because migrated settings, port conflicts, or user changes can alter the final ports. Run ss -lntp to confirm directly whether the relevant ports are in LISTEN state.

Once the ports exist, test the SOCKS and HTTP paths separately. For SOCKS, use socks5h; the h means domain resolution also goes through the proxy. If the test returns HTTP response headers, the local client, selected node, and destination have established a basic connection. If only the browser fails, focus troubleshooting on the desktop proxy and browser proxy settings.

ss -lntp | grep -E '10808|10809'

curl -I --proxy socks5h://127.0.0.1:10808 https://v2rayair.com/
curl -I --proxy http://127.0.0.1:10809 https://v2rayair.com/

systemd User-Level Autostart

Linux desktop applications are best run as systemd user services rather than system-level services under /etc/systemd/system. A user service runs after the desktop account logs in and can inherit the user directory, D-Bus session, and graphical environment. A system-level service may start before the login screen appears, when no graphical session is available, preventing the v2rayN window and tray state from being created correctly.

Before creating the service, run command -v v2rayN. The example below uses the common path /usr/bin/v2rayN; if the command returns another path, you must update ExecStart. Save the service file in the current user's ~/.config/systemd/user/ directory. Do not use sudo for this process.

mkdir -p "$HOME/.config/systemd/user"

cat > "$HOME/.config/systemd/user/v2rayn.service" <<'EOF'
[Unit]
Description=v2rayN Linux desktop client
After=graphical-session.target network-online.target
PartOf=graphical-session.target

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

[Install]
WantedBy=graphical-session.target
EOF

systemctl --user daemon-reload
systemctl --user enable --now v2rayn.service

Restart=on-failure restarts the process only after an abnormal exit, so normally closing the client does not create a continuous restart loop. RestartSec=5 adds a five-second delay to prevent rapid repeated launches when the configuration is wrong. PartOf=graphical-session.target ends the service with the graphical session, which suits a client with a window and tray interaction.

Some desktop environments do not actively start graphical-session.target, or the user manager may not receive the Wayland, X11, and D-Bus environment variables in time. Import the environment first, then restart the service. If the service reports success but no window appears, check whether DISPLAY, WAYLAND_DISPLAY, and DBUS_SESSION_BUS_ADDRESS are present in systemctl --user show-environment.

systemctl --user import-environment DISPLAY WAYLAND_DISPLAY XDG_CURRENT_DESKTOP DBUS_SESSION_BUS_ADDRESS
dbus-update-activation-environment --systemd DISPLAY WAYLAND_DISPLAY XDG_CURRENT_DESKTOP DBUS_SESSION_BUS_ADDRESS

systemctl --user restart v2rayn.service
systemctl --user status v2rayn.service
journalctl --user -u v2rayn.service -b --no-pager

• Loaded is loaded: systemd has read the service file, and the syntax and path can at least be parsed.
• Active is active (running): the v2rayN main process is still running, but you must also check the Xray core and listening ports.
• Status 203/EXEC: the ExecStart path is wrong, the file does not exist, or it is not executable.
• Repeated restarts within a short time: read the last 30 lines of the log and check for a damaged configuration, a port conflict, or missing graphical environment variables.
• Manual launch works, autostart fails: compare the environment variables in the login terminal with those provided by the systemd user manager.

If the desktop environment does not enable graphical-session.target, you can change the service installation target to default.target, but retain the graphical environment import. After editing, run systemctl --user disable v2rayn.service, edit the service file, then run systemctl --user daemon-reload and systemctl --user enable --now v2rayn.service. Do not configure both a systemd service and a desktop autostart entry, or two launch requests may occur at login.

Verify the System Proxy and Routing

After autostart works, distinguish between “the client started” and “the system proxy took over”. v2rayN can start the core after launch, but whether the system proxy is restored automatically depends on the client settings, desktop environment, and previous exit state. After logging in, check the tray status first, then open “Settings” → “Parameter settings” to review startup behavior and system proxy options.

The system proxy mainly affects applications that read the desktop proxy configuration. Terminal curl, package managers, and development tools may ignore the desktop settings or read only the http_proxy, https_proxy, and all_proxy environment variables. Therefore, “the browser works but the terminal does not” usually means the two programs use different proxy entry points, not that the routing rules have failed.

When verifying routing, switch v2rayN to global proxy mode first to confirm that the node and transport path work, then return to rule mode. If global mode works but rule mode does not, the issue is more likely a mismatch in domain, IP, geosite, geoip, or outbound tags. If neither mode works, check the node parameters, time synchronization, DNS, and core logs first.

VMess is sensitive to system clock drift, and VLESS Reality also depends on the correct domain, port, server name, fingerprint, and public key parameters. Run timedatectl status and confirm that System clock synchronized is yes. If the clock is not synchronized, enable the system network time service and test the connection again.

1. Run systemctl --user status v2rayn.service to confirm that the desktop client process is running.
2. Run ss -lntp to confirm that the configured SOCKS or HTTP port is listening.
3. Use an explicit curl --proxy command to verify the local proxy entry point without relying on the desktop environment.
4. Open the desktop network proxy page and confirm that the address is 127.0.0.1 and the port matches.
5. Test global and rule modes separately to determine whether the failure is in the basic connection or route matching.
6. Run journalctl --user -u v2rayn.service -b and retain the log trail for this boot cycle.

timedatectl status
systemctl --user status v2rayn.service
ss -lntp | grep -E '10808|10809'
journalctl --user -u v2rayn.service -b -n 30 --no-pager

Common Installation and Autostart Issues

Most Linux desktop deployment problems fall into four categories: a mismatched package, a changed executable path, an unimported graphical session environment, or a port conflict. Checking the installation, process, core, and system proxy layers in order is more effective than repeatedly uninstalling and reinstalling.

After upgrading v2rayN, run command -v v2rayN again to confirm that the package manager has not changed the launch path. Then restart the user service and check the logs. If a subscription update fails, first verify that the subscription URL is complete, the system time is correct, and the current network can reach the subscription service. If the subscription must be updated through an existing node, enable the corresponding proxy update option in the subscription settings.

If you created a systemd user service, run systemctl --user disable --now v2rayn.service before uninstalling. Then remove ~/.config/systemd/user/v2rayn.service and reload the user services. This prevents the user manager from trying to launch an executable that no longer exists after the package is removed.

systemctl --user disable --now v2rayn.service
rm "$HOME/.config/systemd/user/v2rayn.service"
systemctl --user daemon-reload
systemctl --user reset-failed