Check the distribution, architecture, and desktop environment before installing

When installing v2rayN on Linux, do not start by running an installation command. First identify the package format used by the system. Debian, Ubuntu, and common derivatives generally use deb packages; Fedora, openSUSE, and distributions built around the RPM package system use rpm packages. Choosing the wrong format will not make the system convert it automatically.

You also need to check the processor architecture. Typical desktop computers report x86_64, which may appear as x64 on the download page. Some devices report aarch64 or arm64. The package architecture must match the system architecture; otherwise, the package manager may report a mismatch or the program may fail during startup.

uname -m
cat /etc/os-release

Use uname -m to check the processor architecture. /etc/os-release lists the distribution name, version, and identifier. Do not identify the distribution from the desktop's appearance alone: desktop environments such as GNOME and KDE Plasma can run on different distributions.

Debian and Ubuntu users can also run the command below to confirm the architecture recognized by the package manager:

dpkg --print-architecture

Fedora and openSUSE users can query the architecture with RPM:

rpm --eval '%{_arch}'

v2rayN is a desktop client. The startup, system proxy, and autostart steps in this guide assume a Linux system with a graphical desktop session. If a device only provides a terminal, installing a desktop client is usually not the right deployment approach. Even if installation succeeds, the main window may not open without a graphical session, display service, or desktop components.

Four things to verify before downloading

  • Distribution family: Confirm whether you need deb or rpm; do not guess from the file icon.
  • Processor architecture: Match the package architecture to the output of uname -m.
  • Desktop session: Make sure you can log in normally to GNOME, KDE Plasma, or another desktop environment.
  • Existing installation: If v2rayN is already installed, quit the running client before upgrading or reinstalling.

Open the client download page on this site to get the package. After the download finishes, verify in the file manager that the file is actually in the download directory, then open a terminal. Depending on the browser, the file may be saved in “Downloads,” a directory you selected, or the last directory used; the terminal path must match the actual location.

Install deb packages on Debian and Ubuntu

On Debian and Ubuntu, prefer apt install for installing a local deb package. Unlike running dpkg -i alone, APT analyzes the package's declared dependencies and attempts to install them from the software sources configured on the system. The ./ in the command matters: it specifies a local file in the current directory rather than a package with the same name from a repository.

Step 1: Enter the download directory and confirm the filename

cd ~/Downloads
ls -lh v2rayN*.deb

Some localized Chinese desktop environments display the download directory under a translated name, while the actual path may still be determined by the XDG user-directory configuration. If ~/Downloads does not exist, query the actual download directory first:

xdg-user-dir DOWNLOAD

Then enter the directory returned by the command. After running ls, you should see the complete deb filename. The filename may change with each release, so use the name currently downloaded to your computer.

Step 2: Install the local package with APT

sudo apt update
sudo apt install ./v2rayN-linux-64.deb

The filename above illustrates the command structure. If the downloaded filename differs, replace the end of the command with the complete name shown in the terminal. When entering your sudo password, the terminal normally shows no asterisks or dots; this is expected. Press Enter when finished.

apt update refreshes the package index; it does not upgrade the entire system automatically. Refreshing the index helps avoid cases where a dependency exists but cannot be found in the current index. If the network is unavailable and the dependency was not previously installed, APT cannot fetch the required component.

Step 3: Fix dependencies left by a dpkg installation

If you previously ran sudo dpkg -i and saw messages such as “dependency problems” or “package is not configured,” do not keep repeating the same dpkg command. Let APT repair the unfinished dependency state first:

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

The first command checks for missing dependencies and installs them; the second continues configuring packages that have been unpacked but not fully configured. Afterward, run the local deb installation command again. If the system reports that a dependency package cannot be found, check whether the distribution release is still supported, whether the software sources are available, and whether the package targets your current release.

Step 4: Launch from the application menu

After installation, search for v2rayN in the desktop application menu first. If the menu contains the entry, the system has recognized the desktop file. If the icon does not appear immediately, log out and back in to the desktop session, or inspect the executable command from a terminal:

command -v v2rayN
v2rayN

The second command is useful for observing terminal output during startup. If the window appears normally, close the terminal and test launching from the application menu. If the terminal says the command does not exist, do not guess the installation path; check the package contents to find the actual location first:

dpkg -L v2rayn | grep -E 'bin/|applications/'

Package names and their exact capitalization may change between releases. If the command says the package is not installed, run dpkg -l | grep -i v2ray first, then use the package name shown in the results.

Install rpm packages on Fedora and openSUSE

RPM is a package format; DNF and Zypper are the package managers that resolve dependencies, use repositories, and complete the installation. Running the low-level rpm -i command can install a file, but unlike DNF or Zypper it does not actively resolve dependencies. Desktop users should therefore prefer the distribution's built-in higher-level package manager.

Fedora: Install with DNF

Enter the download directory and verify the file first:

cd ~/Downloads
ls -lh v2rayN*.rpm

After confirming that the file exists, run:

sudo dnf install ./v2rayN-linux-64.rpm

Recent Fedora releases may use a newer DNF implementation internally, but the method for installing a local rpm remains the same. Read the transaction summary before installing, paying particular attention to items being installed, upgraded, or removed. Under normal circumstances, installing a local client should not require removing large portions of the desktop stack.

If an installation was interrupted, check the RPM database and installed state first:

rpm -qa | grep -i v2ray
sudo dnf check

dnf check detects dependency problems among installed packages. If the error comes from an unfinished system update, complete the current package transaction before reinstalling v2rayN. This usually restores a consistent state more reliably than repeatedly forcing an overwrite.

openSUSE: Install with Zypper

openSUSE users should likewise confirm the rpm file in the download directory, then let Zypper resolve it:

cd ~/Downloads
ls -lh v2rayN*.rpm
sudo zypper install ./v2rayN-linux-64.rpm

Zypper may present several dependency-resolution options. Prefer the option that preserves the desktop environment and core system libraries. If an option requires a broad downgrade or replacement of core components, cancel it and verify that the package matches the current distribution release.

After installation, use the command below to view the locations of files in the package:

rpm -ql v2rayn | grep -E 'bin/|applications/'

If the package name differs from the command, run rpm -qa | grep -i v2ray first to obtain the exact name. If the application menu has not refreshed, log out of the desktop session and back in. You can also launch it once from a terminal to retain the complete error message.

First launch, subscription import, and core verification

A v2rayN window opening only confirms that the desktop program is installed; it does not mean the proxy path is ready. After the first launch, proceed in this order: “import configuration, update the subscription, select a node, start the core, and enable the system proxy.” Complete each step before moving on to distinguish subscription, node, and desktop proxy issues quickly.

  1. Import the subscription: Add the complete subscription URL under subscription groups or subscription settings, save it, and run an update manually.
  2. Check the node list: Confirm that server entries appear after the update and that the protocol fields match the information provided by the server.
  3. Select the active node: Choose the entry you plan to use and set it as the current active server.
  4. Start the core: Watch the log area and confirm there are no messages about a port conflict, configuration parsing failure, or core startup failure.
  5. Configure the system proxy: Enable automatic system proxy configuration only after the core is running normally.

VMess and VLESS are different proxy protocols. The client generates the corresponding core configuration from the node settings; users do not need to manually rewrite one protocol as the other. If no nodes appear after a subscription update, first verify that the subscription URL is complete and still valid, and check whether the update returned an error. Reinstalling the client will not fix an empty subscription response, because package installation and subscription delivery are separate stages.

The v2rayN desktop client can generally work with Xray or V2Fly-family cores; available options depend on the current release. If an existing subscription uses a particular transport or protocol extension, choose a core that can parse those parameters. After switching cores, restart the relevant process and check the logs for unsupported fields or configuration parsing errors.

Check the logs first, then locate the failed connection layer

A log message such as “listening port started” usually means the local proxy entry is ready; it does not guarantee that the remote connection succeeded. The actual connection is triggered when you access a destination. If the log says the local port is already in use, change the local listening port in v2rayN settings or stop the old process occupying it.

ss -lntp
ps -ef | grep -i v2ray

ss -lntp shows TCP ports currently in the listening state. Regular users may not see details for every process; use sudo ss -lntp when necessary. If two v2rayN instances are running, the later one may be unable to bind to the same local port. Fully quit the old instance from the tray before reopening the client.

Linux desktop system proxy settings

Core operation and the system proxy are separate states. The core creates a local proxy port and connects to the remote server; the system proxy tells desktop applications to send requests to that local port. If you start only the core without configuring the system proxy, browsers and other applications may still connect directly.

After choosing automatic system proxy configuration in v2rayN, open the desktop environment's network or proxy settings and confirm that the HTTP, HTTPS, or SOCKS fields have changed accordingly. The exact display depends on the desktop environment and client version. Do not copy a port from another computer; use the local port shown in the current v2rayN settings.

GNOME desktop check

GNOME users can open “Settings,” go to proxy settings under “Network,” and check whether the mode is Manual and the address points to the local machine. You can also use a command to view the current proxy mode:

gsettings get org.gnome.system.proxy mode
gsettings get org.gnome.system.proxy.http host
gsettings get org.gnome.system.proxy.http port

When the client controls the proxy automatically, avoid repeatedly changing the setting manually in GNOME at the same time. Operating both sides can leave the client showing that the proxy is enabled while the desktop has saved a different port. Before closing v2rayN, use the client's “Clear system proxy” option or equivalent action to restore the desktop's normal connection method.

KDE Plasma desktop check

KDE Plasma users can view the configuration on the network proxy page in System Settings. Menu locations vary slightly between Plasma releases, but the checks are the same: the proxy address should point to the local machine, and the port should match v2rayN's current listening port. Applications that were already open may need to be restarted to read the new settings.

Why browsers and terminals behave differently

Some applications follow the desktop system proxy, some have their own network settings, and some command-line tools only read environment variables. Therefore, “the browser works but terminal commands bypass the proxy” does not necessarily indicate a core failure. First determine which proxy source the application uses, then decide whether it needs separate configuration.

To make the current terminal session use the proxy temporarily, set environment variables according to the listening type and port shown by v2rayN. The commands below show only the structure; the port must match the client interface:

export http_proxy=http://127.0.0.1:10808
export https_proxy=http://127.0.0.1:10808
export all_proxy=socks5://127.0.0.1:10808

If the current port is not 10808, replace it with the actual value. These temporary variables disappear when the terminal closes. Do not write them to a shell startup file before confirming the local port, or every new terminal will point to a nonexistent proxy entry.

Configure autostart after login

For a desktop client, “start at boot” usually means “start automatically after the user logs in to the graphical desktop.” v2rayN needs a desktop session, tray, and user configuration directory, so it is not suited to being forced to start early as a system-wide background service. Prefer the startup option in the client settings; if it does not work in the current desktop environment, use the XDG autostart directory.

Method 1: Enable the built-in client option

  1. Open v2rayN settings and find the option to start at boot or after login.
  2. Save the settings and fully quit the client.
  3. Log out of the current desktop user, then log back in.
  4. Check the tray icon, process list, and logs to confirm that only one instance started.
  5. Confirm that the client restores the system proxy state as expected after startup.

Test by logging out and back in rather than merely closing the window. Some desktop environments interpret closing the main window as minimizing to the tray, leaving the process running and preventing a real test of autostart.

Method 2: Copy the existing desktop entry to autostart

Package installations usually provide a desktop entry file. Find it first, then copy it to the current user's autostart directory:

find /usr/share/applications -iname '*v2rayn*.desktop'
mkdir -p ~/.config/autostart
desktop_file="$(find /usr/share/applications -iname '*v2rayn*.desktop' | head -n 1)"
test -n "$desktop_file" && cp "$desktop_file" ~/.config/autostart/

After copying, log out and back in. If the first command returns nothing, use the package file list to confirm where the desktop file was installed; do not create a startup entry pointing to an unknown executable path. On deb systems, use dpkg -L to query it; on rpm systems, use rpm -ql.

If two v2rayN instances appear after login, both the client's built-in startup entry and the manually copied XDG entry are active. Keep only one method. You can remove the duplicate in the user directory:

rm -f ~/.config/autostart/*v2rayN*.desktop
rm -f ~/.config/autostart/*v2rayn*.desktop

Before deleting anything, run ls -la ~/.config/autostart to inspect the files. Linux filenames are case-sensitive, so the commands handle common capitalization variants separately. Removing an autostart entry does not uninstall v2rayN or delete subscriptions and client settings.

Avoid starting the desktop window as a system-level service

Turning a graphical client directly into a system-level service commonly leaves it unable to find the graphical display, connect to the user session, read the correct home directory, or creates configuration files with administrative ownership. Desktop users should use the built-in client option or XDG autostart. Consider an additional service-management setup only when you understand user services, the desktop-session environment, and the program's startup parameters.

Troubleshoot common installation and startup failures

Package reports an architecture mismatch

Run uname -m again and compare it with the architecture marked on the downloaded file. An x64 package cannot be installed directly on an arm64 system, and the reverse is also true. An architecture mismatch is not a missing dependency; installing more runtime libraries will not fix it.

Double-clicking the package does nothing

Double-click installation in a file manager depends on a desktop package-installation frontend. If the frontend is missing, a permission prompt is hidden, or the file association is broken, double-clicking may produce no visible feedback. Use APT, DNF, or Zypper instead; the terminal shows the error text directly and makes it easier to distinguish a path, architecture, or dependency problem.

The window is blank or exits immediately after launch

Launch the client from a terminal first and retain the complete output. Check that the desktop session is working, the system graphics components are complete, and the package matches the current distribution release. If you have just completed a major system upgrade, log out or reboot so the newly installed graphics libraries and desktop components load fully.

Also check permissions on the user configuration directory. If the graphical client was previously launched directly with sudo, some configuration files may belong to the administrative user, preventing the regular user from writing to them. Do not run v2rayN with administrative privileges long term. Inspect the owners of relevant files in the user directory, then fix permissions only for directories confirmed to belong to the client.

The client starts normally, but websites cannot connect

Check four layers in order: first, confirm that a node is selected; second, verify that the core started successfully and is listening on the local port; third, check that the system proxy points to that port; fourth, confirm that the target application follows the system proxy. Do not delete the subscription or reinstall the client as a first step.

If only some websites fail, also inspect the routing rules. v2rayN can choose direct access, proxying, or blocking based on domains, address ranges, or rule sets. An incorrect rule may send the request through an unsuitable route. For testing, temporarily switch to an easier-to-diagnose routing mode, confirm that the basic path works, then restore the previous mode and review custom rules one by one.

The subscription updates successfully, but the list does not change

First confirm that the correct subscription group was updated and review the update log. Some subscription responses may be empty or contain data the client cannot parse. Check the subscription URL, group settings, and format provided by the server. A successful package installation does not mean the subscription content is valid; handle the two issues separately.

After reboot, the system proxy points to an inactive port

This usually means the system proxy was restored before the client was ready, or v2rayN failed to start automatically. Clear the desktop system proxy first, start the client, and confirm the core port; then enable automatic system proxy configuration again. Next check for duplicate autostart entries, crashes after login, and another program occupying the local port.

Order of operations for uninstalling, reinstalling, and upgrading

Quit v2rayN before upgrading to prevent the old process from holding files or the local port. When installing a new release through the same package system, APT, DNF, or Zypper will normally treat it as an upgrade transaction. Read the transaction summary first and confirm the package name and architecture.

If you need to uninstall, clear the system proxy and quit the client first. On Debian and Ubuntu, query the exact package name before removing it with APT; on Fedora and openSUSE, query the package name with RPM and pass it to the appropriate manager. Do not delete individual files under /usr, because the package database will still consider the program installed.

dpkg -l | grep -i v2ray
rpm -qa | grep -i v2ray

Uninstalling the application and deleting user configuration are separate actions. A normal uninstall usually preserves subscriptions, routing, and interface settings in the user directory so they can be restored after reinstalling. If the problem is caused by configuration content, reinstalling the package alone may not help. To reset the client, back up any necessary subscription information first, then use the client's reset feature or act only after confirming the configuration directory.