Install v2rayN on Linux: DEB and RPM Packages, Autostart Setup

Before you install: distribution, architecture, and desktop session

On Linux, choose the Avalonia desktop version of v2rayN; the WPF version is for Windows. DEB and RPM are package formats for different distributions, not proxy protocols or core types. Run the command below in a terminal to identify your system. Your desktop environment also affects system proxy settings and autostart.

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

When uname -m returns x86_64, the package is usually for x64; aarch64 usually means arm64. Debian package metadata may use amd64 for the same processor architecture. Check the current Linux downloads on the downloads page. The steps below apply only to a package in the matching format; not every release offers both formats.

Debian and Ubuntu: install a DEB package with apt

For this installation, place the package in its own directory and open a terminal there. First list the DEB files in the current directory, then enter the path to the package—for example, drag the file into the terminal. Using a variable preserves spaces in the filename. Don't select multiple older versions at once.

find "$PWD" -maxdepth 1 -type f -name '*.deb' -print
read -r -p 'Enter the full path to the DEB file: ' pkg
if [ -f "$pkg" ]; then
  dpkg-deb -f "$pkg" Package Version Architecture
  dpkg --print-architecture
else
  printf 'File not found. Select it again.\n'
fi

Check that the package architecture matches your system before installing. apt install can resolve dependencies declared by a local package, making it a better choice for most desktop users than simply unpacking the files. You need administrator authorization for the initial installation, but that does not mean you should run the client as an administrator.

if [ -f "$pkg" ]; then
  pkg="$(realpath "$pkg")"
  sudo apt update
  sudo apt install "$pkg"
fi

• If dependency downloads fail, check that your package sources are available and try again. Don't bypass dependency checks to force the installation.
• If the package architecture doesn't match, choose another download. Don't bypass the check with force-install options.
• After installation, search for v2rayN in your desktop's application list. If no launcher appears, use dpkg -L "$(dpkg-deb -f "$pkg" Package)" to see which files the package actually installed.
• To update the same package, run the local package installation command again. Replacing program files does not back up subscriptions or routing settings, so save important settings before updating.

Fedora: install an RPM package with dnf

On Fedora, use dnf to install a local RPM package. Before installing, read its name, version, and architecture rather than assuming the application's display name is the correct package-manager identifier. The command below reads the actual file; the package name comes from its metadata, not a hard-coded value in this guide.

find "$PWD" -maxdepth 1 -type f -name '*.rpm' -print
read -r -p 'Enter the full path to the RPM file: ' pkg
if [ -f "$pkg" ]; then
  pkg="$(realpath "$pkg")"
  rpm -qp --queryformat '%{NAME} %{VERSION}-%{RELEASE} %{ARCH}\n' "$pkg"
  uname -m
  sudo dnf install "$pkg"
else
  printf 'File not found. Select it again.\n'
fi

After installation, run rpm -ql "$(rpm -qp --queryformat '%{NAME}' "$pkg")" to find the program and desktop launcher files. If v2rayN appears in the application list but immediately exits, run the executable path recorded in its desktop launcher from a terminal and check for missing libraries or core startup errors. Don't keep reinstalling packages for different architectures.

First connection: subscriptions, listening ports, and system proxy

A successful installation means the client can run; it does not mean a remote connection is ready. v2rayN manages nodes and configuration, while the selected core handles the connection. VMess and VLESS are protocol names. A subscription URL retrieves a list of nodes; it is not the same as a local HTTP or SOCKS endpoint.

1. Add a subscription

   Open “Subscription Group” → “Subscription Group Settings,” add a group, and enter a subscription URL you trust. Button locations can vary by version; use the group management option in your current interface.

2. Update the list

   Choose the update option from the “Subscription Group” menu. Before you have a connection, select an update method that doesn't use a proxy. If the URL can't be reached directly, you'll need to establish a working connection first; repeatedly clicking update won't help.

3. Select a node

   Choose a node from the list and set it as the active server. Make sure its protocol and transport settings match the server requirements, then check the log for the core startup result.

4. Check the port

   Go to “Settings” → “Parameter Settings” and check the local listening address and port. This guide uses 127.0.0.1:10808 as an example of a mixed-protocol endpoint. If your interface shows a different port, use that value in all subsequent tests.

5. Set the proxy

   Test an explicit proxy connection first, then try the client's “System Proxy” → “Set System Proxy” option. On Linux, which apps use it depends on the desktop environment and whether each app reads the corresponding settings.

These values are examples, not performance benchmarks or defaults for every version. Test with both protocols only after confirming the endpoint supports HTTP and SOCKS. socks5h tells curl to send the destination hostname to the proxy for resolution, which can help distinguish local DNS issues from proxy connection problems.

ss -ltnp 'sport = :10808'
curl --noproxy "" --proxy http://127.0.0.1:10808 \
  --max-time 15 --head https://example.com
curl --noproxy "" --proxy socks5h://127.0.0.1:10808 \
  --max-time 15 --head https://example.com

Start at desktop login: reuse the existing desktop launcher

Here, “start on boot” means start after you log in to the graphical desktop. It does not run a background service at system startup or provide a proxy at the login screen. Run the client and verify it manually first, then add it to autostart. That way, the same configuration error won't be triggered again at every login.

Prefer the desktop file included with the package. It usually has the correct Exec path and required arguments, making it more reliable than guessing where the executable is. The command below searches standard application directories for launchers. If you find more than one, inspect each and choose only the one belonging to this installation.

find /usr/share/applications "$HOME/.local/share/applications" \
  -maxdepth 1 -type f -iname '*v2rayn*.desktop' -print 2>/dev/null

read -r -p 'Enter the full path to the verified desktop file: ' desktop_file
if [ -f "$desktop_file" ]; then
  grep -E '^(Type|Name|Exec|TryExec|Hidden|OnlyShowIn|NotShowIn)=' "$desktop_file"
fi

Before copying the file, confirm that Type=Application is set, Exec points to the installed program, and nothing prevents it from launching in your current desktop. The destination is the current user's XDG autostart directory, so this command doesn't need sudo. If the old file contains Hidden=true, find out why it was disabled before copying it.

if [ -f "$desktop_file" ]; then
  autostart_dir="${XDG_CONFIG_HOME:-$HOME/.config}/autostart"
  mkdir -p "$autostart_dir"
  cp -- "$desktop_file" "$autostart_dir/v2rayN.desktop"
fi

• After logging out and back in, check that v2rayN starts, the core is running, and the local port is listening.
• If the client already has built-in autostart enabled, remove any second autostart entry to avoid running it twice.
• If the network isn't ready when you log in, the client window appearing doesn't mean the subscription update or node connection will succeed immediately. Check the logs once the network is available.
• To disable the autostart entry created by this guide, run rm -- "${XDG_CONFIG_HOME:-$HOME/.config}/autostart/v2rayN.desktop". This only removes the autostart file.

Permissions and system proxy: troubleshoot by symptom

The local proxy, desktop system proxy, and TUN operate at different levels. An app can connect to a local port over HTTP or SOCKS; desktop proxy settings provide information to apps that choose to read them; TUN involves a virtual network device, routing, and additional permissions. Verify the local proxy first, then expand the scope to reduce troubleshooting steps.

On GNOME, go to “Settings” → “Network” → “Network Proxy” to check manual proxy settings. HTTP and HTTPS proxy fields can point to a local endpoint that supports HTTP; the SOCKS field should point to an endpoint that supports SOCKS. The HTTPS proxy field usually still takes the host and port of a local HTTP proxy—it does not mean the local endpoint needs to provide TLS. Other desktop environments have their own settings; don't copy GNOME-specific commands directly.

# Affects only this terminal and processes started from it
export http_proxy=http://127.0.0.1:10808
export https_proxy=http://127.0.0.1:10808
export all_proxy=socks5h://127.0.0.1:10808

# Clear these settings after testing
unset http_proxy https_proxy all_proxy