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

1. Check your distribution, architecture, and package format

Check your system before choosing a package. Debian and Ubuntu generally use DEB packages; Fedora uses RPM. You can’t switch between the two just by changing a file extension. v2rayN is a client management interface; the core handles proxy connections. Opening the window doesn’t confirm that the core, routing, or proxy interception is working correctly.

cat /etc/os-release
uname -m
getconf GNU_LIBC_VERSION

If uname -m returns x86_64, choose the matching x64 package; if it returns aarch64, choose the ARM64 package. Don’t rely on “64-bit” alone: both processor architectures can be 64-bit. The third command records the glibc version. If the program reports GLIBC_… not found, check the package’s system requirements rather than replacing the system C library.

Choose the Linux package for your architecture from the download center. The commands below assume you’re in the directory containing the package, with only the one DEB or RPM you intend to install there. Don’t run wildcard install commands from a downloads folder containing other packages.

2. Install with apt or dnf and resolve dependencies

Whether you use a graphical installer or the terminal, the package should ultimately be installed through the system package manager. The terminal has the advantage of preserving full error messages. Before installing, check the package name, version, and architecture, and make sure they match the platform you selected.

Debian / Ubuntu: Install a local DEB with apt

# Run this in a directory containing only the target DEB
dpkg-deb -f ./*.deb Package Version Architecture
sudo apt update
sudo apt install ./*.deb

Don’t omit ./: it tells apt to install a local file rather than search the repositories for a package with the same name. If a previous dpkg -i install left dependencies unconfigured, run the following command to fix them. Review apt’s proposed changes first. If it plans to remove the target package, your current repositories may not provide the required dependencies; don’t confirm the operation.

sudo apt --fix-broken install
sudo dpkg --configure -a

Fedora: Install a local RPM with dnf

# Run this in a directory containing only the target RPM
rpm -qpi ./*.rpm
sudo dnf install ./*.rpm

Don’t force an installation by ignoring dependencies. Missing shared libraries, an outdated system version, and the wrong package architecture are different issues. The package manager can install dependencies available in your repositories, but it can’t make software built for a newer runtime work on an older system.

3. First launch: verify the core, then the system proxy

After installation, launch v2rayN from the desktop application menu and run it as a regular user. Don’t use sudo to launch the entire graphical interface: this can create configuration files owned by the administrator and muddle desktop session, proxy, and permission issues. Menu labels may vary slightly by version; the steps below follow the usual layout of the Chinese-language interface.

1. Open the client

   Search for v2rayN in the application menu. If no window appears, find the program referenced by Exec= in the installed desktop launcher, run it in a terminal, and keep the error output.

2. Import a subscription

   Open “Subscription Group” → “Subscription Group Settings,” add a group, and enter a subscription URL from a trusted source. Save it, return to “Subscription Group,” and update the subscription.

3. Start a connection

   Select an entry in the server list and set it as the active server. Check the logs for core startup errors. Protocol settings such as VMess and VLESS must match the server; don’t change transport or security settings at random just to clear an error.

4. Check the port

   Go to “Settings” → “Parameter Settings” and check the local listening address, port, and allowed proxy protocols. Follow your actual configuration, and keep access limited to this machine initially.

5. Enable the proxy

   In the main window, choose “Auto configure system proxy” under “System Proxy,” then check the desktop environment’s network proxy settings. Test applications that follow the system proxy first; don’t enable TUN while troubleshooting.

The commands below use 10808 as an example port; it isn’t necessarily the default for your installation. First confirm that the port is configured for SOCKS or a SOCKS-compatible mixed listener, then run the second command. socks5h sends destination name resolution through the proxy. curl in a terminal won’t necessarily use the proxy just because it’s configured for the desktop.

ss -lntp | grep ':10808'
curl --proxy socks5h://127.0.0.1:10808 --connect-timeout 10 --max-time 30 -I https://example.com/

These commands check whether the local port is listening and whether an explicit request through that proxy succeeds. An HTTP response confirms only that this request worked; it doesn’t mean every application is using the proxy. If the explicit proxy request succeeds but your browser fails, check the browser’s proxy settings, desktop proxy settings, or extensions before reinstalling the core.

4. System proxy differences between GNOME and KDE

Linux doesn’t have a single system proxy switch that applies to every process. Desktop environments typically store proxy settings, but each application decides whether to use them. Terminal programs may also read environment variables such as http_proxy and https_proxy. A working GNOME setting doesn’t mean applications using a separate configuration system will follow it.

When configuring the proxy manually, the address is usually 127.0.0.1; use the port from v2rayN’s actual listener configuration. Don’t enter a SOCKS-only port in an HTTP proxy field. If you manually configured the desktop proxy, restore it before quitting the client; otherwise, applications may keep trying to connect to a local port that is no longer listening.

5. Configure desktop login autostart, not a system service

The desktop client needs a graphical session. For everyday use, it’s better to start it after login than to configure a system-level service that runs as an administrator. Starting after login gives it access to the current user’s desktop proxy, notifications, and configuration directory. A service may run before the desktop is ready and use a different user’s data paths.

In KDE Plasma, go to “System Settings” → “Autostart” → “Add Application” and select v2rayN. In GNOME, use the desktop’s Startup Applications tool. If your distribution doesn’t include one, copy the installed desktop file to the XDG autostart directory. Run the following commands in a regular user’s Bash terminal.

launcher=$(find /usr/share/applications /usr/local/share/applications \
  -maxdepth 1 -type f -iname '*v2rayn*.desktop' -print -quit 2>/dev/null)

if [ -n "$launcher" ]; then
  autostart_dir="${XDG_CONFIG_HOME:-$HOME/.config}/autostart"
  mkdir -p "$autostart_dir"
  cp -- "$launcher" "$autostart_dir/v2rayn.desktop"
  grep -E '^(Name|Exec|TryExec|Hidden|OnlyShowIn|NotShowIn|X-GNOME-Autostart-enabled)=' \
    "$autostart_dir/v2rayn.desktop"
else
  printf '%s\n' 'System desktop launcher not found; check the package file list first.'
fi

Check that Exec= in the output still points to an existing program. If the file contains Hidden=true, an autostart-disabling field, or a desktop-specific field, understand what those fields do before changing them. Don’t invent an executable path if the file isn’t found: use the package manager to list installed files for a DEB, or rpm -ql to list the files in the relevant RPM package.

• To verify: Quit the client completely, log out, and sign in again. Check that only one instance starts, the logs are clean, and the local port is listening.
• Avoid duplicates: Use only one autostart method: the client’s built-in option, the desktop autostart tool, or a manually copied file.
• To undo: Delete the copy you just created at ${XDG_CONFIG_HOME:-$HOME/.config}/autostart/v2rayn.desktop, or remove the corresponding entry from the desktop autostart tool.
• After an upgrade: If the install path changes, copy the new launcher again. A copy in your home directory won’t automatically track updates to the system file.

6. TUN permissions: distinguish the device, authorization, and routing

TUN uses a virtual network device to capture traffic that matches routing rules. It can help with applications that don’t follow the system proxy, but it won’t fix every connection problem. First verify that the regular proxy works, then enable TUN to distinguish server connection issues from local traffic interception issues. On Linux, TUN also involves the device, network management permissions, DNS, and routing changes.

ls -l /dev/net/tun
ip -brief link
ip route show
ip rule show

If /dev/net/tun doesn’t exist, first check whether the system supports TUN and whether it’s loaded. An administrator can run sudo modprobe tun if appropriate for the system. Containers and restricted environments may also need the host to allow device access; changing file permissions alone won’t solve that. Even when the device exists, a regular process may still lack permission to create an interface or modify routes.

• If you see operation not permitted, check virtual interface creation, route changes, and the current authorization procedure.
• If the device is missing, check the TUN device and system environment first; don’t start by changing your subscription.
• If only domain names fail, check DNS handling in the logs; don’t overwrite the system resolver configuration as a first step.
• If problems occur while another tunnel is running, compare routes and policy rules before and after enabling it. Test with only one traffic interception method enabled at a time.

After disabling TUN, check whether routing and network access have recovered. Don’t delete all policy rules in bulk to “restore the network”; this could also break existing desktop connections. If you need unattended startup at login, verify separately that authorization persists. Being able to approve permissions manually doesn’t mean the login process can bypass an authorization prompt.

7. Common installation and autostart questions

For a final check, follow this order: confirm the client starts as a regular user, the core logs are clean, and an explicit proxy request succeeds; verify that desktop applications use the proxy as expected; sign in again to confirm that only one client instance starts; and test TUN last. Record the distribution and client versions, package architecture, and key error lines to make troubleshooting notes useful. Hide subscription URLs, credentials, and other private connection details before sharing them.