Install v2rayN on Linux: deb/rpm packages, desktop integration, and autostart

Check the distribution, architecture, and desktop session first

The Linux version of v2rayN uses an Avalonia desktop interface and follows a different release line from the WPF-based Windows version. It can manage subscriptions, nodes, routing rules, and local proxies in a Linux graphical session, but the package must still match the distribution's package system and CPU architecture. Debian, Ubuntu, and derivatives generally use deb packages; Fedora, Rocky Linux, and other RPM-based systems use rpm packages.

First confirm the system information in a terminal instead of identifying the distribution by its desktop appearance. `amd64` or `x86_64` refers to common 64-bit Intel/AMD devices, while `arm64` or `aarch64` refers to 64-bit ARM devices. Select Linux on the download page, then choose the package for the actual architecture.

cat /etc/os-release
uname -m
echo "$XDG_CURRENT_DESKTOP"
echo "$XDG_SESSION_TYPE"

Install with a deb or rpm package

After downloading, enter the package directory and use the distribution's own package manager. Do not force an unpack with only a low-level tool, as required dependencies for graphics libraries, tray support, or desktop integration may not be installed automatically. Replace the filenames in the commands below with the actual names shown on the download page.

1. Verify the package

   Run ls -lh *.deb *.rpm 2>/dev/null to verify the package type and machine architecture. Do not install an aarch64 build on an x86_64 device.

2. Install the package

   On Debian/Ubuntu, use sudo apt install ./v2rayN-linux-x64.deb; on Fedora, use sudo dnf install ./v2rayN-linux-x64.rpm.

3. Launch the client

   Search for v2rayN in the application menu. If the desktop database has not refreshed, log out and back in, or run v2rayN in a terminal to view the startup output.

4. Choose the core engine

   Open “Settings” → “Parameters” → “Core type”, choose Xray for everyday use with VLESS, VMess, and similar nodes, then save the setting.

5. Import a subscription

   Open “Subscription groups” and add the subscription URL. After updating the group, select a node and check the core log to confirm that it is listening.

# Debian / Ubuntu
cd ~/Downloads
sudo apt install ./v2rayN-linux-x64.deb

# Fedora
cd ~/Downloads
sudo dnf install ./v2rayN-linux-x64.rpm

After installation through APT or DNF, the package manager records file ownership. When a newer package is available, run the same type of installation command again to upgrade in place. Configuration data normally stays in the current user's home directory. Do not launch the graphical client directly as root, or it will create root-owned configuration files that the regular user session cannot read.

Handle dependencies, permissions, and startup failures

Installation failures usually fall into three categories: a mismatched package architecture, missing dependencies in the system repositories, or an incomplete graphical session. If the terminal reports “wrong architecture” or “not supported architecture”, check `uname -m` again. If APT reports unsatisfied dependencies, refresh the system repositories first, then let APT repair the dependency state.

# Update indexes and fix unfinished dependencies on Debian / Ubuntu
sudo apt update
sudo apt --fix-broken install

# Refresh the Fedora cache and retry the local package
sudo dnf makecache
sudo dnf install ./v2rayN-linux-x64.rpm

# Check whether the program is registered in PATH
command -v v2rayN

A program that launches without a tray icon does not necessarily mean the core is not running. GNOME, KDE Plasma, and other desktops implement status trays differently, so check the main window, process list, and core log together. In a Wayland session, the desktop settings or environment variables still control the system proxy; whether the window renders through Wayland or XWayland is a separate issue.

Complete desktop entry and application menu integration

A proper deb/rpm package typically installs a `.desktop` file so v2rayN appears in the application menu. A desktop entry is more than a regular shortcut: it contains the application name, launch command, icon, and category information. System-wide entries are generally stored in `/usr/share/applications/`, while per-user overrides are stored in `~/.local/share/applications/`.

If the application menu does not update immediately, find the actual entry file first and then refresh the desktop database. Do not invent an execution path; use `command -v v2rayN` or query the package file list to confirm where the package installed the program.

# Find the desktop entry installed by the package
find /usr/share/applications ~/.local/share/applications \
  -maxdepth 1 -iname '*v2rayn*.desktop' 2>/dev/null

# List files in the package on Debian / Ubuntu
dpkg -L v2rayn | grep -E 'applications|/bin/'

# List files in the package on Fedora
rpm -ql v2rayN | grep -E 'applications|/bin/'

# Refresh the desktop entry database for the current user
update-desktop-database ~/.local/share/applications 2>/dev/null || true

If the entry exists but the icon still does not appear, log out of the desktop session and back in. Some desktop environments cache the application list, so refreshing the database alone may not rebuild the menu immediately. When editing a `.desktop` file manually, ensure that the `Exec` field does not point to a moved archive directory, save the file as UTF-8 text, and keep `Type=Application`.

Start automatically with the login session

For a desktop client, “autostart at boot” more precisely means “start automatically after the user logs into the graphical session.” It relies on the XDG Autostart specification and should not be configured as a root systemd service. v2rayN needs the current user's display server, tray, configuration directory, and desktop proxy environment; starting before login usually provides none of these.

The safest approach is to reuse the `.desktop` entry supplied by the package and copy it to the current user's `~/.config/autostart/`. This keeps the launch command and icon path consistent with the application menu without requiring the program path to be entered twice.

mkdir -p ~/.config/autostart

desktop_file="$(find /usr/share/applications \
  -maxdepth 1 -iname '*v2rayn*.desktop' -print -quit)"

cp "$desktop_file" ~/.config/autostart/v2rayN.desktop
chmod 644 ~/.config/autostart/v2rayN.desktop

grep -E '^(Name|Exec|Type|Hidden)=' \
  ~/.config/autostart/v2rayN.desktop

• GNOME: Manage per-user autostart items through “Startup Applications”; if the system does not provide that interface, copying the XDG entry works just as well.
• KDE Plasma: Add applications under “System Settings” → “Autostart”, or use `~/.config/autostart/` directly.
• Multi-user devices: Each user should maintain their own autostart entry. Do not place personal subscription configuration in a system-wide directory.
• Temporarily disable: Change `Hidden=false` to `Hidden=true` in the entry, or move the per-user `.desktop` file elsewhere.

Configure the core, system proxy, and routing

A successful installation only means that the client can run. Whether traffic actually enters the proxy depends on the core, node, and system proxy. v2rayN manages the configuration and launches the core; Xray handles protocol connections such as VLESS and VMess; the system proxy directs traffic from applications that support desktop proxy settings to the local listening port. Check these three layers separately.

1. Under “Settings” → “Parameters” → “Core type”, select Xray, save the setting, and restart the core.
2. Add a subscription group, update the subscription, and choose a node with normal latency and availability. Do not import a subscription URL directly as a single-node link.
3. Check the local SOCKS and HTTP listening settings. A common combination is `127.0.0.1:10808` and `127.0.0.1:10809`.
4. Enable the system proxy and test with a regular web browser. If only command-line tools fail, check whether the terminal program reads the desktop proxy settings.
5. Choose global mode or routing rules as needed. Rules are matched in order, so avoid overlapping domain rules, IP rules, and final outbound routes.

Check layer	Where to check	Expected result	First action when abnormal
Clients	v2rayN main window	Subscription groups and node list are visible	Update the subscription again and verify the group status
Core engine	Core log	No port conflicts or configuration parsing errors	Check the core type, ports, and routing rules
Local listener	127.0.0.1	Configured ports such as 10808/10809 are listening	Stop the old process holding the port or change the port
Desktop proxy	System network settings	HTTP/SOCKS point to the local listening address	Run the system proxy setup again
Routing	Routing settings	Target domains use the designated outbound route	Check array order and the final matching rule

For terminal commands such as `curl`, package managers, and other command-line tools, the desktop system proxy may not be applied automatically. When needed, set `http_proxy`, `https_proxy`, or `all_proxy` in the current terminal session, using ports that match v2rayN's local listeners. After testing, use `unset` to clear the variables so later commands do not keep trying to connect to local ports after the client exits.

export http_proxy=http://127.0.0.1:10809
export https_proxy=http://127.0.0.1:10809
export all_proxy=socks5://127.0.0.1:10808

# Clear after testing
unset http_proxy https_proxy all_proxy

Upgrades, removal, and routine maintenance

The main benefit of installing with deb/rpm is that the system package manager continues to track the program files. Before upgrading, exit v2rayN normally, then install the new package for the same architecture. Afterward, check “Settings” → “Parameters” → “Core type”, the local ports, and the autostart entry to confirm that the current user still reads the existing configuration.

When you uninstall the program, APT and DNF remove the registered program files and desktop entry, but subscriptions, logs, and per-user autostart copies may remain in the home directory. If you are only preparing to reinstall, do not delete personal configuration prematurely. If you are finished with the program, back up any routing rules you need, then remove the per-user autostart entry.

# Uninstall on Debian / Ubuntu
sudo apt remove v2rayn

# Uninstall on Fedora
sudo dnf remove v2rayN

# Remove the current user's autostart entry
rm -f ~/.config/autostart/v2rayN.desktop

• After each upgrade, launch the client once and check the core log for configuration migration notices.
• After changing ports, update both the system proxy and terminal environment variables; do not change only one location in the client.
• When a subscription update fails, first distinguish a network timeout, an invalid URL, or a certificate time error before deciding whether to update through the proxy.
• After routing rules change, test the matching result with a specific domain instead of judging routing solely by the node showing “connected”.
• When autostart fails, check the `.desktop` `Exec` path first rather than converting the client into a system service.