Install v2rayN on Linux: DEB/RPM Packages and Autostart

Before you install: identify your distribution, architecture, and desktop session

v2rayN is a desktop client for managing servers, launching the core, and configuring proxy settings. DEB and RPM packages install the application; they do not provide servers or subscriptions. This guide is not for headless servers without a graphical desktop. Don’t treat the desktop client as a system service that runs at boot.

First, check your system information in a terminal. Ubuntu and Debian users will usually want the DEB package; Fedora users will usually want the RPM. In processor names, x86_64 corresponds to x64, and aarch64 to arm64. The same package format does not mean a package can be used across distributions or architectures.

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

Choose a Linux package from the download page. For the commands below, rename the downloaded DEB file to v2rayN.deb or the RPM file to v2rayN.rpm, then open a terminal in that file’s directory. These are local filename conventions only; they do not change the package version, architecture, or package name.

Install DEB/RPM packages and let the package manager handle dependencies

Check the package details before installing. This helps catch issues such as the wrong architecture or file format. Don’t treat a webpage response as an install package or bypass errors with options that force installation despite missing dependencies.

Debian / Ubuntu: install a local DEB with apt

dpkg-deb -f ./v2rayN.deb Package Version Architecture
sudo apt update
sudo apt install ./v2rayN.deb

./ tells the installer to use a file in the current directory; don’t omit it and enter a repository package name instead. Unlike running dpkg -i on its own, apt can resolve dependencies from enabled repositories. If a previous installation stopped because of dependency errors, review the proposed changes from sudo apt --fix-broken install first. Continue only if it won’t remove software you still need.

Fedora: install a local RPM with dnf

rpm -qp --queryformat '%{NAME} %{VERSION}-%{RELEASE} %{ARCH}\n' ./v2rayN.rpm
sudo dnf install ./v2rayN.rpm

If dnf reports missing dependencies, check your distribution version, repository status, and whether the package is intended for your system. Don’t copy Debian libraries to Fedora or create symlinks for shared libraries to fake a dependency. Being able to unpack a package doesn’t mean the application will run correctly.

1. Inspect package details

   Check the package’s Version and Architecture. Debian’s amd64 and the common RPM architecture x86_64 both refer to x64.

2. Install the package

   Run the appropriate apt or dnf command. Keep the specific error from the terminal instead of noting only that the installation failed.

3. Launch the client

   Search for v2rayN in the desktop applications menu and launch it as your current user. Don’t use sudo to launch a graphical application.

4. Import a server and test the connection

   Copy a share link, then right-click the server list in the main window and select “Import share links from clipboard.” Select a server and choose “Set as active server.” The exact labels may vary by version.

Proxy setup: check the listener before configuring the desktop proxy

A successful installation is only the first step. Check that the active server works, the core is running, and a local inbound listener is available. Open Settings → Parameter Settings to review the local listening port and related inbound settings, then check the client logs to confirm what actually started. These settings may appear under different tabs in different versions, so don’t rely on old screenshots to find them.

The examples below assume the client provides an HTTP proxy or mixed inbound on 127.0.0.1:10808. If your port is different, update both the desktop settings and test commands. If the port accepts SOCKS traffic only, don’t enter it in an HTTP proxy field. There’s usually no need to change the listening address to 0.0.0.0, which could expose the proxy port to other devices.

The HTTPS proxy field means “use this proxy when accessing HTTPS sites”; it doesn’t mean you need to run a TLS proxy locally. An HTTP proxy can forward HTTPS requests using CONNECT. A system proxy does not route all traffic: some terminal programs, standalone network components, and apps with their own proxy settings won’t follow the desktop configuration.

• Use one configuration method at a time. If the client can configure the desktop proxy correctly, use its settings; otherwise, enter the details manually in the desktop settings.
• For a manual setup, add local addresses to the bypass list, for example localhost,127.0.0.1,::1. Use the separator required by your desktop environment.
• Start with the regular system proxy for your first connection. Consider TUN mode only if needed; it requires additional permissions and routing configuration.

Verify the connection: check the port, request, and browser separately

Latency numbers in the server list don’t replace a full connection test. A successful TCP connection only suggests the destination port is reachable. A real connection test is closer to an actual proxy request, but you should still test in a browser. Check the listener first, send a request with a command that explicitly specifies the proxy, then confirm whether desktop apps are using the proxy settings.

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

# Use an HTTP proxy explicitly to rule out desktop proxy settings
curl --noproxy "" --proxy http://127.0.0.1:10808 \
  --connect-timeout 5 --max-time 15 \
  -I https://example.com/

example.com is a public example site. This command tests the request path; it is not a subscription URL. Receiving HTTP response headers means that this request got a response through the specified proxy. It doesn’t prove that every site or routing rule works. If curl isn’t installed, run sudo apt install curl on Debian/Ubuntu or sudo dnf install curl on Fedora.

If the browser follows the system proxy, it will usually need to start a new connection. If that doesn’t help, fully quit and reopen it. Don’t change DNS, routing, the server, and the listening port all at once; you won’t know what caused the result. Change one thing at a time, and note the request time and corresponding log entries.

Autostart: use a desktop login entry, not a system service

Here, “start at boot” means “start after the user logs in to the graphical desktop.” The desktop session doesn’t exist while the computer is sitting at the login screen. v2rayN depends on a graphical session and user-specific settings. Running it as a system service is not a substitute for a desktop login entry and can cause problems with the display environment, permissions, and configuration directories.

Find the desktop entry installed with the package

Package builds may use different executable paths and desktop filenames, so don’t guess the value for Exec. Run one of the command blocks below, matching your package format, from the directory containing the package. Use the package metadata to find the actual desktop entry.

# Debian / Ubuntu
pkg=$(dpkg-deb -f ./v2rayN.deb Package)
dpkg -L "$pkg" | grep -E '/applications/[^/]+\.desktop$'

# Fedora
pkg=$(rpm -qp --queryformat '%{NAME}' ./v2rayN.rpm)
rpm -ql "$pkg" | grep -E '/applications/[^/]+\.desktop$'

In your file manager, copy the v2rayN desktop file you found to the current user’s ~/.config/autostart/ directory. Create the directory first if it doesn’t exist. If XDG_CONFIG_HOME is set, use its autostart/ subdirectory instead of assuming the default path.

mkdir -p "${XDG_CONFIG_HOME:-$HOME/.config}/autostart"

• Before copying the file, open it and confirm that Exec= points to the installed program. Keep its existing arguments; don’t replace them with a guessed path.
• Check for Hidden=true or fields that restrict the desktop environment. An existing disable entry may prevent the app from starting at login.
• In GNOME, add the app using an installed Startup Applications tool. In KDE Plasma, go to System Settings → Autostart and add it there. The settings category may vary by version.
• Choose either desktop settings or copying the file. Don’t create two login entries, which could start duplicate clients or cause a port conflict.

Once configured, log out and back in to test the login entry; simply closing the window is not enough. Confirm that only one client instance is running, then check the listening port and proxy status. A login entry only launches the program. Whether it automatically connects to the active server or configures the system proxy depends on separate options in your version.

Common issues: dependencies, desktop entries, and port conflicts

When troubleshooting, keep the distribution version, architecture, package version, and complete error lines. This is far more useful than repeatedly reinstalling. Don’t run the client as an administrator to mask a permissions problem; this could make root the owner of your user settings and prevent them from being saved during the next regular launch.

Upgrade or roll back: keep user settings and check the login entry

For future upgrades, install the new DEB or RPM using the same package manager. Quit the client before upgrading, then back up your user data with the client’s backup feature or from its actual configuration directory. Configuration paths can vary by version and packaging method, so don’t assume the program directory is also the settings directory. Backups may contain subscription credentials; store them somewhere only your current user can access.

1. Confirm that the new package supports your distribution and processor architecture.
2. Quit the client, then run the local package installation command for your distribution from above.
3. Launch the client once and check the active server, listening port, and request result.
4. Check the executable path in the user login entry, then log out and back in to test it.

To disable the client temporarily, turn off the system proxy first, quit the client, and then disable its desktop login entry. To uninstall it, use apt or dnf with the actual package name you found earlier. Copies of the login entry and settings in your user directory may remain, so check them separately. Uninstalling the program does not restore your desktop proxy settings.