Install v2rayN on Linux: DEB/RPM Packages and Desktop Autostart

1. Check Your Distribution, Architecture, and Package Type

Ubuntu and Debian users typically need a DEB package; Fedora users typically need an RPM package. Package format and CPU architecture are separate requirements: a DEB package may target either x86_64 or ARM64. Run the command below, then visit the installer downloads page and choose the Linux package that matches your system. This guide doesn't assume a specific version; check the download page for currently available packages.

cat /etc/os-release
uname -m

x86_64 usually appears as x64 or amd64 on the download page; aarch64 usually appears as arm64. Don't rename a package to make one architecture's build appear compatible with another. These steps require a graphical desktop and a regular user account; don't follow the desktop autostart instructions on an SSH-only server.

2. Install the DEB Package on Ubuntu or Debian

Put the downloaded DEB file in a dedicated directory, making sure it contains only the one package you want to install. Then choose “Open in Terminal” from your file manager. The commands below work in Bash and read the actual package name from its metadata, so they don't depend on how the downloaded file is named.

# The current directory must contain only one DEB package to install
set -- ./*.deb
if [ "$#" -eq 1 ] && [ -f "$1" ]; then
  pkg=$(dpkg-deb -f "$1" Package)
  dpkg-deb -f "$1" Package Version Architecture
  sudo apt update
  sudo apt install "$1"
else
  printf '%s\n' 'Run this from a directory containing only the target DEB package.'
fi

The relative path in sudo apt install ./filename.deb matters: it tells apt to install a local file, not a package from a repository. apt will try to resolve the declared dependencies from your configured repositories. If you see an “unmet dependencies” error, check your distribution version, package architecture, and repository configuration. Don't force the installation by ignoring dependencies.

1. Check the Package Details

   Review the Package, Version, and Architecture values in the output above. Make sure they match the package you just downloaded and your system architecture. Note the Package value for later queries and removal.

2. Finish the Installation

   Review apt's transaction summary and wait for the installation to finish. If apt update fails, fix the repository or network issue before continuing.

3. Find the Launcher

   Run the query below in the same terminal to find the desktop launcher and executable included in the package. Don't assume the application is installed in a particular directory.

4. Launch v2rayN for the First Time

   Open your desktop's application menu, search for v2rayN, and launch it as your regular user. Installation requires administrator privileges, but that doesn't mean you should use sudo for everyday use.

# Continue using the pkg variable set in the previous step
dpkg -L "$pkg" | grep -E '/applications/.*\.desktop$|/bin/'

3. Install the RPM Package on Fedora and Check Dependencies

On Fedora, use dnf to install a local RPM package. As with the DEB steps, put the target RPM in its own directory and open a Bash terminal there. Don't keep multiple versions or architectures in the directory, or you might install the wrong file.

# The current directory must contain only one RPM package to install
set -- ./*.rpm
if [ "$#" -eq 1 ] && [ -f "$1" ]; then
  pkg=$(rpm -qp --queryformat '%{NAME}' "$1")
  rpm -qp --queryformat '%{NAME} %{VERSION}-%{RELEASE} %{ARCH}\n' "$1"
  sudo dnf install "$1"
else
  printf '%s\n' 'Run this from a directory containing only the target RPM package.'
fi

# After installation, check the launcher in the same terminal
rpm -ql "$pkg" | grep -E '/applications/.*\.desktop$|/bin/'

If the installation succeeds but clicking the launcher opens no window, find the Exec= line in the package's .desktop file and run the actual executable path in a terminal to see any error output. If the line contains desktop entry field codes such as %U or %F, don't pass those fields to the terminal when testing manually.

• Missing shared library: Note the exact library name in the error. On Fedora, a query such as dnf provides '*/libX11.so.6' can identify the package that provides it. Replace the example library name with the one from your error.
• ICU or runtime error: First check whether the package bundles its own runtime, then verify which distributions it supports. ICU package names and versions vary across distributions; don't blindly install a list of outdated dependencies.
• Can't connect to the display server: Make sure you launched the app from a logged-in graphical session, not a regular SSH session or a system-level startup task.
• Window opens, but the tray icon is missing: Check whether your desktop environment supports tray icons. A missing tray icon doesn't mean the app failed to install or that its proxy core has exited.

Wait until the desktop app is running properly before configuring the network. Don't disable SELinux, loosen permissions across the entire installation directory, or run the client as root just to get rid of a startup error.

4. Set Up the Desktop Launcher and Verify the Proxy

DEB and RPM packages usually install an application menu entry. Prefer the package's existing .desktop file, which contains the correct executable path, working directory, or launch arguments. If the entry doesn't appear in the application menu, try logging out and back in. Create one manually only if the package has no launcher.

To create a launcher manually, use a text editor to fill in the fields above and save the file as ~/.local/share/applications/v2rayN.desktop. First, confirm that the file referenced by Exec actually runs. If the path contains spaces, quote it according to the desktop entry specification. Don't use a temporary extraction path in your downloads directory as a permanent launch path.

1. In the main window, open “Subscription Group” → “Subscription Group Settings,” add the subscription URL from your service provider, and save. Menu names may vary slightly between versions.
2. Return to the “Subscription Group” menu and choose “Update All Subscriptions.” Once your nodes appear, select one as the active server.
3. Go to “Settings” → “Parameter Settings” and check the local listen port and inbound protocol. For the initial test, keep the standard local proxy mode and leave TUN disabled.
4. Check the runtime log to confirm that the core started successfully. Then test an explicit proxy connection and the desktop system proxy separately to pinpoint any issue.

# First confirm that the client is listening on this port
ss -lntp | grep ':10808'

# Use only if this inbound listener supports SOCKS
curl --proxy socks5h://127.0.0.1:10808 --connect-timeout 10 -I https://example.com/

socks5h sends domain name resolution to the proxy side. Use this command to test the current SOCKS inbound and node connection. If only an HTTP inbound is enabled locally, use its actual port and http://127.0.0.1:port instead. A successful explicit proxy test confirms only that this route works; it doesn't prove that every desktop app automatically follows the system proxy.

5. Start v2rayN Automatically at Login

Linux desktop clients rely on your graphical user session. The easiest options to maintain are your desktop environment's Startup Applications settings or copying a verified launcher to ~/.config/autostart/. Choose one method; don't also enable the client's internal autostart setting or add a separate user service.

The steps below use Debian and Ubuntu as examples and continue using the pkg variable from the installation steps. If you closed the terminal, look up the actual package name with the package manager and set the variable again. List the launcher files first, and confirm which one you need before copying. Don't just pick the first of several candidates.

dpkg -L "$pkg" | grep -E '/applications/.*\.desktop$'

Open the desktop file found by the query in a text editor. Check its Exec= line, and make sure it doesn't contain Hidden=true or an OnlyShowIn= setting that excludes your desktop. Then copy that file to the autostart directory. You can also run the interactive command below and paste the full path.

read -r -p "Enter the absolute path to the verified .desktop file: " desktop
if [ -f "$desktop" ]; then
  mkdir -p "$HOME/.config/autostart"
  cp -- "$desktop" "$HOME/.config/autostart/v2rayN.desktop"
else
  printf '%s\n' 'File not found. Check the path and try again.'
fi

On Fedora, replace the query command with rpm -ql "$pkg". The checks and copy steps are the same. Exit v2rayN normally, then log out and back in to confirm that only one instance starts. If your desktop doesn't support tray icons, leave “Start minimized” disabled during the initial test so you can tell whether the app is running.

6. Troubleshoot When Autostart Works but the Proxy Doesn't

“The app is open” and “apps are using the proxy” are two different things. The network may not be ready just after you log in, and subscription updates may fail. That doesn't mean you need to reinstall the software. Check where the failure occurs in this order.

• No process or window: Run the launcher's actual Exec command manually and check that an upgrade hasn't changed the path. Make sure your desktop settings haven't disabled the autostart entry.
• Window opens, but the port isn't listening: Check the runtime log for core startup errors. Verify the active node, check for port conflicts, and make sure the core executable has permission to run.
• Explicit curl proxy test fails: Check the protocol and port first, then test the node connection, system time, and any requirements from your service provider. Authentication for connections such as VMess can be affected by clock skew.
• curl works, but the browser doesn't: Check the browser's own proxy settings and extensions, then check your desktop's “Settings” → “Network” → “Network Proxy.” The exact location varies by desktop environment.
• Browser works, but terminal commands don't: Command-line tools may need environment variables or their own proxy options. The desktop system proxy doesn't automatically apply to every command-line program.
• Two instances start: Check your desktop autostart list, the client's own settings, and any user services you created. Keep just one startup method.

On Linux, the system proxy is usually a configuration interface provided by the desktop environment; it doesn't force all traffic through the proxy. Routing rules make a separate decision—whether to proxy or bypass traffic after it reaches the core. These are different stages. Verify the basic connection before enabling TUN to avoid dealing with permissions, DNS, and routing issues all at once. For more help, see the troubleshooting guide.

7. Upgrade, Remove Autostart, and Uninstall

Before upgrading, exit the client, note the installed package name, and back up the user configuration directory that the client actually uses. Find its location in the app's directory options or runtime log; don't assume every version stores data in the same place. Configuration may contain subscription credentials, so keep backups somewhere only your user can access.

1. Download the new package for the same architecture, then upgrade with apt install ./filename.deb or dnf install ./filename.rpm.
2. Launch the app manually once. Check the subscription, active node, and local port, then make sure the Exec path in the autostart copy is still valid.
3. If you change the installation method or application directory, create a new desktop launcher instead of using the old path.

# Remove only the login autostart entry created in this guide; do not uninstall the app
rm -f "$HOME/.config/autostart/v2rayN.desktop"

# Choose one removal method; pkg must be the verified package name
# Debian / Ubuntu:
sudo apt remove "$pkg"

# Fedora:
sudo dnf remove "$pkg"

Before uninstalling, restore your desktop network proxy settings and exit the app to avoid leaving the system pointed at a local port that is no longer listening. Uninstalling a package usually doesn't remove all files in your user directory. If you want to clean them up, first check what's there and what you backed up. You now have a repeatable process for installing, launching from the desktop, testing the proxy, and starting at login.