Install v2rayN on Linux: DEB/RPM Packages and Autostart

1. Check Your Distribution, CPU Architecture, and Installation Method

v2rayN is a graphical desktop client; cores such as V2Ray and Xray handle the actual connections. Installing the client, starting a core, and routing applications through a proxy are separate steps. This guide covers installation and the desktop session—it does not apply the Android client workflows for v2rayNG or v2flyNG to Linux.

Open a terminal and check your distribution and machine architecture. Debian and Ubuntu users typically choose DEB; Fedora users choose RPM. Other distributions may also use RPM, but first confirm that your distribution meets the package's dependencies. The file extension alone does not guarantee compatibility.

cat /etc/os-release
uname -m

Choose Linux and the matching architecture on the client download page. For the commands below, rename the downloaded file in your file manager to v2rayn-linux.deb or v2rayn-linux.rpm, then open a terminal in the folder containing it. Renaming only makes the commands shorter; it does not change the package's internal version, package name, or architecture.

2. Install the DEB or RPM Package and Resolve Dependency Errors

Use apt or dnf to install a local package instead of running a lower-level installation command alone. The package manager can resolve dependencies from enabled repositories. If those repositories are unavailable, installation will still fail; fix your network or repository configuration first rather than skipping dependency checks.

Debian / Ubuntu: Install a Local DEB with apt

# Run this from the directory containing the DEB file
dpkg-deb -f ./v2rayn-linux.deb Package Version Architecture
sudo apt update
sudo apt install ./v2rayn-linux.deb

./ specifies a file in the current directory. Without it, apt may treat the input as a package name from a repository. If a previous dpkg -i installation left dependencies unconfigured, run the repair command below. Review apt's proposed installations or removals before proceeding, then retry the local package installation.

sudo apt --fix-broken install

Fedora: Install a Local RPM with dnf

# Run this from the directory containing the RPM file
rpm -qp --queryformat '%{NAME} %{VERSION}-%{RELEASE} %{ARCH}\n' ./v2rayn-linux.rpm
sudo dnf install ./v2rayn-linux.rpm

• Architecture mismatch: Check uname -m again. Do not force-install a package for a different architecture.
• Missing dependency: Note the full package or library name, then check whether the repository is enabled and supports your OS version.
• File conflict: Check where the existing installation came from before proceeding. Do not overwrite files in system directories without checking.
• Library version too old: Check the client's system requirements first. Do not copy core libraries from another distribution into system directories.

3. First Launch: Check the Subscription, Listening Ports, and System Proxy Separately

After installation, search for v2rayN in your desktop application menu. First confirm that the main window opens, then import your connection configuration. Menu labels vary by version; this guide refers to common desktop labels such as “Subscription groups,” “Settings,” and “Parameter settings.” If your version uses different wording, follow the corresponding functions rather than looking for Android menu locations.

1. Launch the client

   Start v2rayN from the application menu. If no window appears, run the program specified by Exec= in the desktop launcher from a terminal to check for missing libraries or display-session errors.

2. Import a subscription

   Go to “Subscription groups” → “Subscription group settings,” add a group, enter a remark and subscription URL, and save. Then update it from “Subscription groups.” To import a shared link, use the clipboard import option on the main screen.

3. Select a server

   Select an available configuration from the list and set it as the active server. Subscription or shared links provide settings for VMess, VLESS, and other protocols. Do not change the transport, TLS, or server address at random just to troubleshoot.

4. Check the listeners

   Go to “Settings” → “Parameter settings,” check the local listening ports under Basic settings, and review the logs for core startup failures or port conflicts. After saving, restart the relevant services as prompted by the client.

5. Set the system proxy

   Open the “System proxy” menu on the main screen or in the system tray and select “Set system proxy automatically.” Then check your desktop environment's network proxy settings. Verify separately whether each application follows those settings.

The two ports below are common examples for illustration, not guaranteed defaults for every version. Use the values in your local settings. If the client uses a single mixed port, test the protocols supported by that inbound listener; there is no need to add a second listener.

# Check for the corresponding TCP listener; adjust the port to match your local settings
ss -lntp | grep -E ':(10808|10809)\b'

# Test only after confirming the listener protocol; curl must be installed
curl --connect-timeout 10 --max-time 20 \
  --proxy socks5h://127.0.0.1:10808 https://example.com/

curl --connect-timeout 10 --max-time 20 \
  --proxy http://127.0.0.1:10809 https://example.com/

A curl request with an explicitly specified proxy can help distinguish an unavailable proxy from an application that is not using one. socks5h sends the destination hostname to the proxy for resolution. A successful request does not mean every application is using the proxy. System proxy settings are also separate from routing modes: rules such as “Global” or “Bypass mainland China” determine how requests that reach the core are routed; they cannot make applications that ignore the system proxy use it.

4. Missing System Tray Icon? Check Your Desktop Environment First

Tray icon support depends on the status icon mechanism provided by your Linux desktop environment. If the main window and core work but the tray icon is missing, check desktop integration before reinstalling the client. GNOME in particular may not have application indicator support enabled by default.

• GNOME: Open your system's extension manager and check whether AppIndicator / KStatusNotifierItem support is available and enabled. On Debian/Ubuntu, start by searching the repositories with apt search appindicator; on Fedora, use dnf search appindicator. Package names and available versions vary by distribution.
• KDE Plasma: Right-click the system tray to open its settings. Check whether the application's status is set to hidden under “Entries,” and look in the collapsed items area.
• Xfce: Check that the panel includes a tray plugin that supports status notifications. Without a panel to host the icon, client settings alone cannot add a tray icon.
• Remote or minimal desktop: Confirm that the current session is running a panel and tray component, not just a window manager.

After installing or enabling a desktop extension, save your work and log out and back in. This is usually more useful for diagnosis than repeatedly killing the client. Do not use desktop restart shortcuts from another session in a Wayland session. If the main window itself will not open, check the startup error in a terminal; a tray extension cannot fix a missing runtime library.

5. Start the Client Automatically at Desktop Login

A graphical client should start with your desktop session. The XDG autostart directory ~/.config/autostart/ is designed for this. It does not launch before the login screen and does not require changes to /etc/rc.local or a root scheduled task. Confirm that the client runs successfully by hand before adding it to autostart; this makes problems easier to isolate.

Find the desktop launcher installed by the package

Use the original package to query its file list. This preserves the launch path, arguments, and icon set by the publisher. Run only the commands for your package format; if you moved the package file, first go to its current directory.

# Debian / Ubuntu
pkg_name=$(dpkg-deb -f ./v2rayn-linux.deb Package)
dpkg -L "$pkg_name" | grep -E '/applications/.*\.desktop$'

# Fedora
pkg_name=$(rpm -qp --queryformat '%{NAME}' ./v2rayn-linux.rpm)
rpm -ql "$pkg_name" | grep -E '/applications/.*\.desktop$'

From the output, choose the .desktop file that launches the main window. If the package includes multiple launchers, check their Name= and Exec= entries first. Do not copy an uninstaller or utility launcher. Next, run the commands below in a Bash terminal and paste the full path found in the previous step when prompted, without quotes.

read -r -p "Paste the full path to the main window .desktop file: " desktop_file

if [ -f "$desktop_file" ]; then
  mkdir -p "$HOME/.config/autostart"
  install -m 644 "$desktop_file" \
    "$HOME/.config/autostart/v2rayn.desktop"
  sed -i '/^Hidden=/d; /^X-GNOME-Autostart-enabled=/d' \
    "$HOME/.config/autostart/v2rayn.desktop"
  grep -E '^(Name|Exec|TryExec|Hidden|OnlyShowIn|NotShowIn|X-GNOME-Autostart-enabled)=' \
    "$HOME/.config/autostart/v2rayn.desktop"
else
  printf '%s\n' "File not found; no autostart entry created."
fi

This preserves the launch command from the original launcher and removes two options that may prevent autostart. If OnlyShowIn= or NotShowIn= remains, check whether its desktop environment restrictions match your session. Do not replace Exec= with a guessed program path, or put ~, a pipe, or & in it; desktop launchers are not interpreted like ordinary shell scripts.

Test, disable, and check again after upgrades

1. Use the client's actual “Exit” command and make sure no windows or duplicate instances remain.
2. Save your work, log out, and log back in. Check that v2rayN starts and the local listeners are available again.
3. Confirm that the system proxy settings match your expectations. Autostarting the program does not automatically select a server or restore every proxy setting.
4. To disable autostart, run the removal command below. It removes only the user's autostart copy and does not uninstall the client.

rm -f "$HOME/.config/autostart/v2rayn.desktop"

If the client also offers a built-in autostart option, use either that or the manual entry, not both, to avoid duplicate launches. After an upgrade that changes the installation path or launch arguments, copy the launcher from the new package again. The old copy in your autostart directory will not update automatically when the system copy changes.

6. Common Questions About Installation and Autostart

A reliable setup order is: install the package, confirm it runs as a regular user, verify the proxy connection, then test autostart at login. Move to the next step only after each one works; this helps keep dependency, tray, and remote connection issues separate. For more initial setup steps, see the Getting Started guide. For protocol fields and routing concepts, see the protocol handbook.