v2rayN Linux Desktop Installation Guide: DEB/RPM Packages, Desktop Shortcuts, and Autostart

Check the distribution, architecture, and desktop session first

Linux packages depend on more than the distribution name: verify both the package format and CPU architecture. Debian, Ubuntu, and derivatives generally use DEB; Fedora, Rocky Linux, and other RPM-based desktop distributions generally use RPM. An x86_64 device matches x64 or 64-bit packages, while ARM64 devices require arm64 packages. They are not interchangeable.

v2rayN is a desktop client that relies on a graphical session, a system tray, and the current user's configuration directory. A command-line-only remote server is not suitable for this approach. Common desktops such as GNOME and KDE Plasma work, but whether the tray icon appears directly depends on status-icon support in the desktop environment. A missing tray icon does not mean the core failed to start.

Run the commands below in a terminal to confirm the architecture. On Debian-based systems, amd64 usually maps to x64 packages and arm64 to ARM64 packages; RPM-based systems commonly report x86_64 or aarch64. If you download the wrong architecture, the installer will report a package-architecture mismatch. Installing more dependencies will not fix it.

dpkg --print-architecture

uname -m

rpm --eval '%{_arch}'

• amd64 or x86_64: choose the Linux x64 package.
• arm64 or aarch64: choose the Linux ARM64 package.
• Graphical session check: run echo "$XDG_CURRENT_DESKTOP". A normal desktop login usually returns a name such as GNOME or KDE.
• systemd version check: run systemctl --version. Modern desktop distributions such as Ubuntu 24.04 LTS already support user services.

Install the DEB package on Debian and Ubuntu

Install DEB packages with APT rather than calling the lower-level dpkg directly. APT reads the local package and resolves available dependencies from configured repositories, making missing runtime libraries easier to diagnose. Keep ./ in the command: it tells APT to use the local file in the current directory instead of searching repositories for a package with the same name.

1. Download the package

   Open the client download page, select Linux, and download the v2rayN DEB package matching your CPU architecture. Save it in the current user's Downloads directory.

2. Change to the directory

   Open a terminal and run cd ~/下载; English-language directory setups usually use cd ~/Downloads. Then run ls to verify the actual filename.

3. Install the package

   Run sudo apt install ./v2rayN-linux-*.deb, verify the package name and architecture, and continue when prompted.

4. First launch

   Search for v2rayN in the desktop application list and launch it. Run the first launch as a regular desktop user; do not prefix the command with sudo.

5. Check the core

   Open “Settings” → “Parameter Settings” → “Core Type”. When using VLESS, VMess, or similar nodes, make sure the Xray core is selected.

cd ~/Downloads
sudo apt install ./v2rayN-linux-*.deb

# English user directory can be
cd ~/Downloads
sudo apt install ./v2rayN-linux-*.deb

If APT says it cannot locate the file, run pwd and ls -lh first to verify that the terminal is in the same directory as the download. A wildcard expands only when a matching file exists in the current directory. Keeping multiple versions can make the command match several packages; in that case, enter the complete filename to avoid passing both old and new versions to the installer.

After installation, use command -v v2rayN to find the launch command and dpkg -l | grep -i v2rayn to view the package-manager record. Use the executable path provided by the package's desktop entry rather than assuming every distribution uses the same directory.

Install the RPM package on Fedora-based distributions

Fedora desktops use DNF to handle local RPM packages. Unlike the lower-level rpm command, dnf install resolves dependencies and records the installation in the normal package database. Keep ./ in the local path; otherwise DNF may search repositories for a package by name.

1. Verify the architecture

   Run uname -m. Choose an x64 package for x86_64 and an ARM64 package for aarch64; do not rely only on the device brand.

2. Install the RPM

   Change to the Downloads directory and run sudo dnf install ./v2rayN-linux-*.rpm. Review the dependency list, then confirm the installation.

3. Refresh the application entry

   After installation, search for v2rayN in the application list. If the desktop is still showing an old menu cache, log out of the current session and sign in again.

4. Select the core

   After launching, open “Settings” → “Parameter Settings” → “Core Type”, then choose the Xray or v2ray core according to the node protocol.

5. Test the connection

   Import a subscription and update the nodes. Select a node, enable the system proxy, then check the connection-test result and log timestamps.

cd ~/Downloads
sudo dnf install ./v2rayN-linux-*.rpm

# English user directory can be
cd ~/Downloads
sudo dnf install ./v2rayN-linux-*.rpm

When you see an “architecture not supported” error, choose the correct package instead of adding another repository. If a system library is missing, run sudo dnf upgrade --refresh to refresh repository metadata, then reinstall the local RPM. If the distribution version is no longer maintained, missing dependencies often indicate unavailable repositories; upgrading the distribution is usually the better solution.

First launch, subscription imports, and the system proxy

On first launch, v2rayN creates configuration and log data in the current user's directory. The key rule is to always run the client under the same regular desktop account. Launching it with sudo first and switching to a regular account later can create mismatched ownership, causing settings not to save, subscription updates to fail, or logs to become unwritable.

A subscription URL and a single-node share link are different types of data. A subscription URL provides an updateable list of nodes for long-term management; a vmess:// or vless:// share link usually contains just one node. After importing a subscription, run an update. A group name without a server list often means the subscription has not been updated, the address was copied incompletely, or the system clock is significantly wrong.

1. Open the subscription management screen, add a subscription group, and paste the complete URL.
2. Run Update All Subscriptions and wait for the node list to appear before choosing a server.
3. Open “Settings” → “Parameter Settings” and verify the local listening port. A common initial value is 10808, but always use the value shown in the interface.
4. Open “Settings” → “Parameter Settings” → “Core Type”. VLESS nodes usually use the Xray core; for traditional VMess nodes, choose the compatible core according to the server configuration.
5. After enabling the system proxy, reconnect the browser. Existing long-lived connections may continue using the network path from before the switch.

When a connection fails, check the logs first instead of changing every option at random. If the logs show that the port is already in use, run ss -lntp to inspect listening processes near 10808, then choose an unused port in Parameter Settings. After changing the port, update the desktop proxy and any applications with manually configured proxy settings.

Missing desktop icon or no response on click

After a normal DEB or RPM installation, the desktop menu entry usually comes from a desktop file under /usr/share/applications. If the app does not appear immediately, the desktop menu cache may simply need refreshing. If clicking the icon opens nothing, check the Exec path in the desktop file, execute permissions, and the current user's logs.

grep -R "^Exec=" /usr/share/applications 2>/dev/null | grep -i v2rayn
command -v v2rayN
ls -l "$(command -v v2rayN)"

• Desktop entry is present: verify that the file referenced by Exec exists, then try running the same command from a regular user's terminal.
• Starts from the terminal but not the menu: log out of the desktop session and sign in again so the application menu rereads its entry files.
• Already running in the background: check the tray area and process list. Clicking again may only activate the existing instance rather than create a second window.
• Configuration directory permission error: use find ~/.local/share -maxdepth 2 -iname '*v2rayn*' -ls to check ownership. Do not delete configuration that is still in use.
• Tray missing under Wayland: confirm the main window from the window list first, then check status-icon support in the desktop environment. Do not mistake a tray issue for a core that failed to run.

If the client was previously run with sudo, exit the process completely and check ownership of the relevant user configuration directories. Use chown only after confirming that the files belong to the current user's v2rayN configuration. Do not recursively change permissions across the entire home directory; this can affect browsers, keys, and other desktop applications.

Start automatically after login with a systemd user service

A graphical client should use a systemd user service rather than a system-wide root service. The user service runs after the current account logs in, keeping configuration, logs, and the desktop session under the same user. Before creating the service, run command -v v2rayN to get the actual launch path. The example below uses the common path /usr/bin/v2rayN; if your result differs, change ExecStart to the actual absolute path.

Save the service file in ~/.config/systemd/user. Name it v2rayn-desktop.service to distinguish it from a system service. Set Restart to on-failure so it restarts only after an abnormal exit; a normal exit initiated by the user will not create a restart loop.

mkdir -p ~/.config/systemd/user
nano ~/.config/systemd/user/v2rayn-desktop.service

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

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

[Install]
WantedBy=default.target

After saving the file, reload the user-service configuration, then enable and start it immediately. enable --now both starts the service on future logins and starts it in the current session. Before running it, exit any manually launched v2rayN to prevent two launch paths from competing for the same configuration directory or triggering single-instance limits.

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

• View logs from this boot:journalctl --user -u v2rayn-desktop.service -b
• View the latest 80 lines:journalctl --user -u v2rayn-desktop.service -n 80
• Reload after editing the file:systemctl --user daemon-reload, then run restart.
• Pause automatic startup:systemctl --user disable --now v2rayn-desktop.service

If the service reports a successful start but no window appears, first confirm that it is running under the graphical login user. Then check the logs for missing DISPLAY, WAYLAND_DISPLAY, or desktop-bus variables. The time needed to import session variables into the systemd user manager varies by desktop environment. Do not switch to a root service; instead, manually restart the user service after the desktop has fully loaded to see whether the session environment was not ready.

Upgrades, removal, and common troubleshooting

To upgrade a DEB or RPM package, install the new file directly through the package manager. Before installing, exit v2rayN and record the current version, Core Type, and local port. Afterward, check subscription groups, routing rules, and the system proxy state. Configuration is usually stored in the user directory, so upgrading the package does not reset it, but avoid replacing program files while the client is running.

Before uninstalling, disable the systemd user service; otherwise the service manager will keep trying to start an executable that has been removed. Then remove the software through the distribution's package manager. Decide whether to keep user configuration based on whether you plan to reinstall; do not treat package removal and user-data cleanup as the same step.

1. Run systemctl --user disable --now v2rayn-desktop.service to stop the service and disable autostart.
2. Run systemctl --user status v2rayn-desktop.service and confirm that the process has ended.
3. On Debian/Ubuntu, use dpkg -l | grep -i v2rayn to find the exact package name, then pass it to APT for removal.
4. On Fedora-based systems, use dnf list installed | grep -i v2rayn to find the exact package name, then pass it to DNF for removal.
5. After confirming that automatic startup is no longer needed, delete the user service file and run systemctl --user daemon-reload.

Keep the troubleshooting order consistent: first confirm that the program starts as a regular user, then confirm that the core is listening normally, followed by node connectivity and routing, and finally the system proxy. Changing installation permissions, core protocols, and desktop proxy settings at the same time obscures cause and effect in the logs. Change one variable at a time and record the state at each step; this is usually faster than repeated reinstalls.