How to Install v2rayN on Linux: DEB/RPM Packages and Startup on Login

1. Check Your Distribution, Architecture, and Package Format

v2rayN is a desktop client for managing servers, subscriptions, and core settings. Its Linux package must match both your distribution's package system and your CPU architecture. Ubuntu and Debian generally use DEB packages; Fedora generally uses RPM. The same file extension does not guarantee compatibility with every distribution, so check the system requirements in the download notes.

# Check the distribution and CPU architecture
cat /etc/os-release
uname -m

# Package architecture for Debian / Ubuntu
dpkg --print-architecture

# Package architecture for Fedora
rpm --eval '%{_arch}'

Run only the commands that apply to your distribution. x86_64 usually corresponds to x64 on the download page; Debian packages often label it amd64. aarch64 usually corresponds to ARM64. Do not use a Windows package on Linux, and do not infer the architecture from the computer's brand alone. Visit the Download Center, choose Linux, and use the package format currently offered.

2. Install the Local Package with apt or dnf

Run these commands in a Bash terminal. Enter the full path to the package you downloaded, not the download page URL. Paths containing spaces are supported. The examples do not assume a fixed package name, so you won't accidentally reuse an outdated filename after an update. Installation requires administrator privileges, but you should run the client as a regular user.

Ubuntu / Debian: Install a DEB Package

read -r -e -p "Enter the full path to the DEB file: " package_file
package_file="$(realpath -- "$package_file")"

if [ -f "$package_file" ]; then
  dpkg-deb -f "$package_file" Package Version Architecture
  sudo apt update
  sudo apt install "$package_file"
else
  printf '%s\n' "File not found. Check the path and try again."
fi

When you pass a local file path to apt install, apt resolves dependencies using your configured repositories. If dependencies cannot be met, first check your distribution version, architecture, and repository configuration. Repeatedly forcing the installation will not provide missing runtime components. apt update refreshes repository indexes; it does not upgrade the entire system.

Fedora: Install an RPM Package

read -r -e -p "Enter the full path to the RPM file: " package_file
package_file="$(realpath -- "$package_file")"

if [ -f "$package_file" ]; then
  rpm -qip "$package_file"
  sudo dnf install "$package_file"
else
  printf '%s\n' "File not found. Check the path and try again."
fi

3. First Launch: Import a Subscription, Then Check the Core

After installation, find v2rayN in your desktop application menu and open it. For the first launch, keep the default permissions and use regular proxy mode. TUN involves a virtual network interface, routing, and additional permissions, so it is best handled separately from initial installation troubleshooting. Menu labels may vary by version. The names below are common in the Chinese interface; if you cannot find an exact match, use the equivalent setting in your version.

1. Open the client

   Launch v2rayN from the application menu. If only a tray icon appears, click it to open the main window. Avoid launching multiple instances.

2. Add a subscription

   Go to “Subscription Group” → “Subscription Group Settings,” add a group, and enter the subscription URL and a note. Save, then return to the main window.

3. Update subscriptions

   From the “Subscription Group” menu, select “Update All Subscriptions (Without Proxy).” If you do not have a working node yet, try updating directly first. If it fails, check your network connection and subscription URL.

4. Select an active server

   Choose a valid configuration from the server list, then select “Set as Active Server” from the right-click menu. A successful subscription update does not mean a usable node is selected.

5. Check the listener

   Open “Settings” → “Parameter Settings” to check the local listening address, port, and core options. Then review the runtime log to confirm the core started and that there are no port conflicts.

Subscriptions usually include the node's protocol and transport settings. You do not need to change VMess to VLESS just to install the Linux version, and you should not change TLS, the server name, or the transport path without a reason. If the log says a core file is missing, check whether your package includes the required core and whether the client points to a file that actually exists. This is separate from troubleshooting the system proxy toggle.

4. Linux System Proxy: Match the Listener Port and Desktop Settings

The system proxy affects only apps that read the relevant proxy settings; it does not automatically route every process. First confirm that the client's local proxy works, then configure your desktop environment. The examples below use 127.0.0.1:10808 for illustration, not as a guaranteed default. Check the actual value in Parameter Settings and the runtime log.

In GNOME, go to “Settings” → “Network” → “Network Proxy” → “Manual” to check the configuration. The HTTP and HTTPS fields take the host and port of a local HTTP proxy; the HTTPS field does not mean the proxy server itself must use an HTTPS connection. If the core provides a SOCKS listener, enter it in the SOCKS field rather than treating a SOCKS-only port as an HTTP port. Check the core configuration to see which protocols a mixed listener accepts.

# Check whether the example port is listening
ss -ltnp 'sport = :10808'

# If the port supports HTTP proxying
curl --connect-timeout 5 --max-time 15 \
  --proxy http://127.0.0.1:10808 \
  -I https://example.com

# If the port supports SOCKS5, resolve the destination hostname through the proxy
curl --connect-timeout 5 --max-time 15 \
  --proxy socks5h://127.0.0.1:10808 \
  -I https://example.com

Choose the curl command that matches the listener type; you do not need both to succeed. Specifying --proxy bypasses desktop proxy settings so you can test the “local listener → core → node → destination” path directly. An HTTP response only confirms that this request reached its destination; it does not verify every site, UDP traffic, or all routing rules.

• Local connection refused: Check that the core is running and that the port is correct.
• Local connection works, but the request times out: Check the active node, core logs, destination DNS resolution, and which routing rule is being applied.
• curl works, but the browser does not: Check whether the browser uses the system proxy, has its own proxy settings, or is still running an old session that needs restarting.
• Desktop settings did not change: Some desktop environments do not respond to the client's system proxy controls. Check the settings manually instead of relying on the client's toggle state.

5. What Startup on Login Means: Launching the Desktop App After Sign-In

These instructions configure v2rayN to start automatically after you log in to the graphical desktop—not to run a GUI before the login screen. Before login, there is no user session, display service, or desktop configuration. Creating a system service directly can leave the window invisible or apply proxy settings to the wrong user. Test the client manually before enabling startup to keep troubleshooting straightforward.

For desktop startup, prefer reusing the package's .desktop file rather than guessing where the executable is installed. The commands below use the package_file variable from the installation steps to find the package name and list its startup entries. If you closed the terminal, enter the package path again before running the appropriate command.

# Ubuntu / Debian: Read the actual package name from the DEB and find its startup entry
package_name="$(dpkg-deb -f "$package_file" Package)"
dpkg -L "$package_name" | grep '/applications/.*\.desktop$'

# Fedora: Read the actual package name from the RPM and find its startup entry
package_name="$(rpm -qp --queryformat '%{NAME}' "$package_file")"
rpm -ql "$package_name" | grep '/applications/.*\.desktop$'

Run only the command group for your system. Confirm that the listed file belongs to the v2rayN application before copying it. If there are no results, do not copy another app's startup entry; add the actual launch command through your desktop environment's startup settings instead.

read -r -e -p "Enter the full path to the desktop file you found: " desktop_file

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

6. Verify After Logging In and Troubleshoot Common Issues

After configuring startup, log out and back in; a full system restart is usually unnecessary. Check that the client starts only once, the active server is still selected, and the local port is listening, then repeat the proxy request from earlier. The window, core, and desktop proxy are three separate checks. Seeing a tray icon alone does not confirm that the connection is working.

7. What to Save Before Upgrading or Rolling Back

For future upgrades, use a package that matches the same distribution and architecture, and install it with apt or dnf. The package manager handles program files, while user data such as subscriptions, routing rules, and interface preferences may live in a separate configuration directory. Its location can vary by version and how the app is run. Check the current client's configuration directory entry or logs instead of relying on a fixed path found online.

• Exit the client first: Avoid changes being written in the background while you copy settings. Do not just close the window and leave the app running in the tray.
• Save your user settings: Back up the verified configuration directory and note the active node, routing presets, listening port, and startup method. Subscription URLs may contain credentials; do not post them in public logs.
• Run it manually after upgrading: Check the core log and local listener, test an HTTP or SOCKS request, and then verify startup.
• Consider data format compatibility before rolling back: Newer versions may write data that older versions cannot read. If you need to roll back, use a configuration backup from before the upgrade rather than repeatedly overwriting the application.

With these steps, Linux v2rayN deployment breaks down into four clear checks: the package installs, the client and core start, app traffic actually reaches the proxy, and the client starts again at login. Troubleshoot one layer at a time; this is more effective than changing nodes, routing, and TUN settings all at once. For more on proxy modes, see System Proxy and Proxy Modes. For routing changes, see the Routing Configuration Reference.