v2rayN Linux Installation Guide: deb/rpm Package Installation, Desktop Shortcuts, and Autostart

Check the system architecture and desktop session before installation

First confirm the processor architecture in a terminal instead of choosing a package based only on the distribution name. Most desktop computers report x86_64, which corresponds to the 64-bit or x64 package on the download page; some ARM devices report aarch64 and require the arm64 package. These packages cannot be mixed. Choosing the wrong architecture usually produces “package architecture does not match” or “cannot execute binary file” errors.

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

/etc/os-release identifies the package family: Ubuntu, Debian, and Linux Mint generally use deb; Fedora, Rocky Linux, and openSUSE distributions in the rpm family use rpm. The desktop session also affects tray and autostart behavior, and the status areas in GNOME, KDE Plasma, and Xfce are not fully identical.

The commands in this guide use a 64-bit test machine: Ubuntu 24.04 with GNOME and Wayland, plus Fedora 42 with KDE Plasma and Wayland. Package filenames may change between releases, so run ls -lh ~/Downloads to verify the actual filename before installing.

Install the deb package on Ubuntu and Debian

Open the client page on this site, select the Linux platform, and download the v2rayN deb package matching your architecture. After downloading, verify the file type, then let APT install the local package. Using apt install instead of a low-level unpacking command allows the package manager to resolve available dependencies from configured repositories.

1. Verify the architecture

   Run uname -m. Choose the 64-bit package for x86_64, or the arm64 package for aarch64.

2. Get the package

   Open the Linux tab on the client page, download the deb file, and save it in the current user’s Downloads directory.

3. Install the package

   Run the local installation command from the Downloads directory. APT reads the package metadata and fills in available dependencies from the configured software sources.

4. Choose the core

   After launching, open “Settings” → “Parameter Settings” → “Core Type”, select Xray, then save and restart the core.

5. Verify the proxy

   Import a subscription and select a node, enable the system proxy, then check that the local listening port and core logs look normal.

cd ~/Downloads
ls -lh v2rayN*.deb
sudo apt update
sudo apt install ./v2rayN-linux-64.deb

If you downloaded an arm64 package, replace the filename in the command with the arm64 filename shown in your terminal. Filenames are case-sensitive, and the leading ./ in the local path is required. After installation, search for v2rayN in the application menu or run command -v v2rayN to locate the executable.

When dependencies are unmet, update the system’s package sources first, then run a repair installation. Do not keep double-clicking the package: a graphical software center may only report “installation failed” without identifying the missing library.

sudo apt --fix-broken install
sudo apt install ./v2rayN-linux-64.deb
apt-cache policy libicu-dev

If the terminal names a specific missing runtime library, install the package with that name from the current distribution’s repository. Copying an individual shared library from another distribution can create version-chain inconsistencies and is not a suitable long-term fix.

Install the rpm package on Fedora and other rpm-based distributions

Fedora uses DNF to install local rpm packages. DNF checks the architecture, signature metadata, and dependencies, then records the installation in the system package database. As with the other command, ./ refers to a local file in the current directory.

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

If the system uses a newer DNF command implementation, the installation syntax remains the same. To upgrade, run the local installation command again for the newly downloaded rpm file; the package manager replaces the older version based on the version number, while user configuration usually remains in the home directory.

After installation, run the commands below to verify the package record and executable entry. If rpm -qa finds the package but command -v returns nothing, use rpm -ql to see which files the package actually installed.

rpm -qa | grep -i v2rayn
command -v v2rayN
rpm -ql v2rayN | grep -E '/bin/|applications'

Complete the first launch, core, and proxy port setup

After the first launch, check the core before enabling the system proxy. Open “Settings” → “Parameter Settings” → “Core Type”, select the Xray core required by your subscription nodes, save the settings, and restart the core once. Parameters for VLESS, VMess, and similar nodes are generally imported with the subscription; manually changing the transport, security, or server address may cause connection failures.

Next, add a subscription URL under “Subscription Groups”, update the subscription, and select a node. To test basic connectivity, start with the latency test on the main screen, then review the runtime log. A latency result only confirms that probing completed; web access also depends on the system proxy, DNS, and routing settings.

After enabling the system proxy, use ss to check local listeners. The command below checks only the common port 10808; if Parameter Settings uses another port, replace the query condition accordingly.

ss -lntp | grep 10808
curl --proxy http://127.0.0.1:10808 https://example.com/ -I

If ss returns nothing, check the core startup error in the v2rayN log first. Common causes include a port conflict, a non-executable core path, failed configuration generation, or incomplete node fields. If the listener is active but the browser still connects directly, check whether the desktop network proxy has switched to the local address provided by v2rayN.

• For local-machine use only, keep the listen address at 127.0.0.1 to avoid exposing the proxy port to the local network.
• After changing the port, update the system proxy settings as well; the old port will not change automatically.
• After switching nodes, watch the log for a new outbound connection instead of relying only on the selected state in the interface.
• For traffic routing, start with the built-in rules, then add domain or IP rules one at a time.

Fix desktop and tray icons

If the package is installed but no icon appears in the application menu, first check whether the desktop entry exists. Standard entries are usually under /usr/share/applications; the current user can also place a personal entry in ~/.local/share/applications. If the desktop database has not refreshed, logging out and back in is usually more direct than reinstalling repeatedly.

find /usr/share/applications ~/.local/share/applications \
  -iname '*v2rayn*.desktop' 2>/dev/null
update-desktop-database ~/.local/share/applications 2>/dev/null || true

If the package did not create a usable entry, create a user-level desktop file. Before running it, use command -v v2rayN to confirm the executable path. If the result is not /usr/bin/v2rayN, use the path returned by the terminal in the file.

mkdir -p ~/.local/share/applications
cat > ~/.local/share/applications/v2rayN.desktop <<'EOF'
[Desktop Entry]
Type=Application
Name=v2rayN
Comment=Proxy client
Exec=/usr/bin/v2rayN
Icon=v2rayN
Terminal=false
Categories=Network;
StartupNotify=true
EOF
chmod 644 ~/.local/share/applications/v2rayN.desktop
update-desktop-database ~/.local/share/applications

Tray issues usually do not prevent the core from running. Use pgrep -af v2rayN and ss -lntp to check the process and port first, then fix the desktop status area separately. This distinguishes a missing interface entry from a proxy core that has not started.

Configure desktop autostart or a systemd user service

Linux desktops commonly offer two autostart methods. XDG desktop autostart follows the graphical session and receives the Wayland, DBus, and tray environment directly, making it suitable for most users. A systemd user service provides restart policies and log access, making it better for environments that require explicit process management.

XDG desktop autostart

If you already created ~/.local/share/applications/v2rayN.desktop, copy it to the current user’s autostart directory. The desktop environment will read the file and launch the program after login.

mkdir -p ~/.config/autostart
cp ~/.local/share/applications/v2rayN.desktop \
  ~/.config/autostart/v2rayN.desktop

If you use the desktop file supplied by the system package, find its actual filename with find and copy it to the autostart directory. To disable autostart, delete only the copy in the user directory; there is no need to uninstall v2rayN.

rm ~/.config/autostart/v2rayN.desktop

systemd user service

Disable XDG autostart before creating the service so two processes do not compete for local ports such as 10808. Store the service file in the current user’s directory. Do not use sudo systemctl enable, which would incorrectly configure a system-level service.

mkdir -p ~/.config/systemd/user
cat > ~/.config/systemd/user/v2rayn.service <<'EOF'
[Unit]
Description=v2rayN 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

If command -v v2rayN returns another path, update ExecStart accordingly. If the Wayland or DBus environment is not inherited by the user service, the program may run without a window or tray icon. After logging in to the desktop, import the session variables first, then restart the service.

systemctl --user import-environment \
  DISPLAY WAYLAND_DISPLAY XAUTHORITY DBUS_SESSION_BUS_ADDRESS
systemctl --user restart v2rayn.service
systemctl --user status v2rayn.service
journalctl --user -u v2rayn.service -n 80 --no-pager

Handle launch failures, port conflicts, and removal

When the program will not start, run it directly from a terminal and preserve the complete error output. Errors from double-clicking a desktop icon usually disappear when the window closes, while terminal output can distinguish shared-library, permission, core-file, and graphical-session issues.

command -v v2rayN
v2rayN
pgrep -af 'v2rayN|xray'
ss -lntp | grep -E '10808|10809'

If the log says an address is already in use, identify the process holding the port from the ss output. Common causes include an older v2rayN version, an autostart service, and a manually launched instance running at the same time. Stop the extra instances and restart the core; do not terminate system processes whose purpose you cannot confirm.

• Choose either desktop autostart or a systemd service to avoid duplicate launches.
• After changing the local proxy port, the browser and desktop system proxy must use the same port.
• If the core fails to start, open “Settings” → “Parameter Settings” → “Core Type” and confirm Xray again.
• If a subscription update fails, check the network and subscription URL first, then decide whether to enable updates through the proxy.
• If problems appear after an upgrade, exit the program, back up the configuration, and reinstall the package for the current architecture.

Use the package manager for the distribution when uninstalling. Removing the package does not automatically delete user configuration; if you need to test a clean setup, back up the v2rayN configuration in the home directory first, then handle it according to the actual path. Do not clear the user directory before backing up subscriptions and custom routing rules.

# Ubuntu or Debian
sudo apt remove v2rayn

# Fedora or similar rpm-based distributions
sudo dnf remove v2rayN

# Disable user service
systemctl --user disable --now v2rayn.service
rm ~/.config/systemd/user/v2rayn.service
systemctl --user daemon-reload

Package names may differ in capitalization and from the registered name. If the uninstall command cannot find the package, deb-based systems can run dpkg -l | grep -i v2ray, while rpm-based systems can run rpm -qa | grep -i v2ray; then use the exact name returned by the query.