Install v2rayN on Linux: Set Up DEB/RPM Packages and Enable Autostart

Before you install: distribution, architecture, and desktop session

v2rayN is a desktop configuration manager; the proxy core it invokes handles the actual connections. This guide covers the graphical client, which requires an active desktop session. It isn’t intended for a headless server. In a terminal as your regular user, run the commands below and note your distribution, processor architecture, and desktop environment.

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

Choose Linux and the matching architecture on the client download page. Don’t use a Windows file as a Linux package or try to convert a package by changing its extension. Run the commands below in Bash. They prompt for the actual file path, so there’s no need to rely on a specific version number or filename.

Install a DEB package: let apt handle dependencies

On Debian or Ubuntu, use apt to install the local DEB package. It resolves dependencies from your configured repositories. Low-level installation commands may unpack the package without resolving dependencies, leaving it in an incomplete state. Paste the absolute file path when prompted; don’t add extra quotes. The following commands already handle quoting the variable.

read -r -p 'Enter the absolute path to the DEB file: ' package_file
dpkg-deb -f "$package_file" Package Version Architecture
sudo apt install "$package_file"

1. Check package details

   Review the package name, version, and architecture in the output, and make sure they match the file you just downloaded. If the architecture is wrong, get the correct package rather than forcing an architecture override.

2. Verify the installation

   Make sure apt completes successfully. If dependencies aren’t available, check your distribution’s repositories and supported versions. Don’t mix system libraries from another distribution.

3. Launch from the applications menu

   Open your desktop’s applications menu, search for v2rayN, and launch it as your current user. Don’t use sudo to start a graphical app; that can leave its configuration files owned by the administrator.

4. Import a subscription and test

   In the main window, go to “Subscription groups” → “Subscription group settings.” Add a link from a trusted source, then update the subscription. Button labels may vary slightly between builds; follow the options shown in your version.

If installation succeeds but there’s no menu entry, first check whether the package includes a desktop file. Run the command below in the same terminal where the package_file variable is still set. If you open a new terminal, enter the file path again first.

package_name=$(dpkg-deb -f "$package_file" Package)
dpkg-query -W "$package_name"
dpkg-query -L "$package_name" | grep -E '/applications/[^/]+\.desktop$'

Install an RPM package: use the command for Fedora or openSUSE

RPM is a package format, not a guarantee that every distribution using it has the same runtime environment. Check the package details, then choose the command for your distribution. Don’t run both dnf and zypper, and don’t bypass dependency checks to hide missing libraries.

read -r -p 'Enter the absolute path to the RPM file: ' package_file
rpm -qp --queryformat '%{NAME}\n%{VERSION}-%{RELEASE}\n%{ARCH}\n' "$package_file"

# Fedora: run this command
sudo dnf install "$package_file"

# openSUSE: run this command instead
sudo zypper install "$package_file"

• Dependencies can’t be resolved: Note the missing package names and check whether your distribution’s repositories provide them. Don’t replace system graphics or cryptography libraries at random.
• Verify the package source: Review the package manager’s prompts and confirm where the file came from. Disabling global verification shouldn’t be part of a routine installation.
• Exits immediately after installation: Check the app’s desktop file for its actual launch command, then run that command in a terminal to see the error. Keep its existing arguments; don’t assume the executable is in a particular directory.

After installation, you can check the package’s application entry. This queries the list of installed files. If the installation transaction failed, fix that first rather than configuring autostart.

package_name=$(rpm -qp --queryformat '%{NAME}' "$package_file")
rpm -q "$package_name"
rpm -ql "$package_name" | grep -E '/applications/[^/]+\.desktop$'

First connection: verify the listener before setting a system proxy

Importing a subscription, starting the core, and routing app traffic through the proxy are separate steps. Select a server you’re authorized to use, then check the logs to confirm the core starts. Go to “Settings” → “Parameters” and look for the local listen address, port, and protocol. Settings may move between client versions, so verify the actual configuration and listener.

These ports are examples, not defaults for every version. Some configurations use a single mixed-protocol listener; others provide separate HTTP and SOCKS ports. Use a port only if a listener is actually available on it. For local desktop use, keep the address on loopback rather than listening on every network interface.

# Adjust the match conditions to the actual ports
ss -lntp | grep -E ':(10808|10809)[[:space:]]'

# Test only after confirming the protocol and port
curl --proxy http://127.0.0.1:10809 --head --max-time 15 https://example.com/
curl --proxy socks5h://127.0.0.1:10808 --head --max-time 15 https://example.com/

socks5h sends destination hostname resolution through the proxy. An HTTP response is evidence that this request reached its destination, but it doesn’t confirm that all routing rules or DNS paths are correct. If the connection is refused, check the listener and core logs first. If the local connection succeeds but the request times out, investigate the server, transport settings, and network.

GNOME and KDE: what system proxy settings do—and don’t—cover

A desktop system proxy is a setting that applications can read; it doesn’t transparently capture all network traffic. Browsers, desktop components, and command-line programs may handle proxy settings differently. Start by testing one application known to support proxies, then move on to others. Avoid changing system settings, browser settings, and environment variables all at once, or troubleshooting becomes harder.

Manual proxy in GNOME

Go to “Settings” → “Network” → “Network Proxy” and select “Manual.” For HTTP and HTTPS, enter a local HTTP proxy that supports HTTP CONNECT; for SOCKS, enter the SOCKS listener port. Selecting HTTPS doesn’t mean the local proxy endpoint must use TLS. The exact location may vary by distribution; you can also use the commands below.

# Record the current values first so you can restore them; run in a terminal for the current desktop user
gsettings get org.gnome.system.proxy mode
gsettings list-recursively org.gnome.system.proxy.http
gsettings list-recursively org.gnome.system.proxy.https
gsettings list-recursively org.gnome.system.proxy.socks

# Run only if the example ports match the active listeners
gsettings set org.gnome.system.proxy.http host '127.0.0.1'
gsettings set org.gnome.system.proxy.http port 10809
gsettings set org.gnome.system.proxy.https host '127.0.0.1'
gsettings set org.gnome.system.proxy.https port 10809
gsettings set org.gnome.system.proxy.socks host '127.0.0.1'
gsettings set org.gnome.system.proxy.socks port 10808
gsettings set org.gnome.system.proxy mode 'manual'

# Stop using the manual system proxy
gsettings set org.gnome.system.proxy mode 'none'

Manual proxy in KDE Plasma

Open “System Settings,” search for “Proxy,” then select “Use manually specified proxy configuration.” Enter the actual HTTP, HTTPS, and SOCKS endpoints, then apply the changes. KDE settings are mainly read by apps that follow the desktop proxy mechanism. Some browsers have their own settings, and command-line tools usually need separate configuration. Switch back to no proxy before quitting the client, or apps may keep trying to connect to a closed local port.

• If your browser still ignores the system proxy, check whether an extension or separate proxy setting is overriding it.
• If curl works with an explicit proxy but regular requests fail, check where the app gets its proxy settings before reinstalling the client.
• Don’t let the client and custom scripts repeatedly overwrite system proxy settings. Choose one way to manage them, then test it.

Autostart: launch after graphical login, not as a system service

For a desktop client, autostart at boot usually means launching after you log in to the graphical desktop. It doesn’t provide a proxy before login. Use the desktop session’s XDG Autostart mechanism and the desktop entry supplied by the package. Preserve its executable path and arguments; don’t guess at the Exec line.

1. Disable duplicate startup entries

   Check “Settings” → “Parameters” in the client for an autostart option. If you plan to use the manual method below, turn that option off first to avoid launching the app twice.

2. Find the desktop file

   Use the package file listing command from earlier to find the actual .desktop path. Make sure the app launches from the applications menu, then provide that path to the copy command below.

3. Copy the user-level entry

   Copy the desktop file to your user’s autostart directory. Don’t modify the system-wide entry. No sudo is needed.

4. Verify after logging in again

   Quit the client, log out of the desktop, and log back in. Check the window or background process, listening port, and system proxy. A tray icon alone doesn’t prove the core is running.

read -r -p 'Enter the absolute path to the installed .desktop file: ' desktop_file
grep -E '^(Type|Name|Exec|TryExec|Hidden|OnlyShowIn|NotShowIn)=' "$desktop_file"

autostart_dir="${XDG_CONFIG_HOME:-$HOME/.config}/autostart"
mkdir -p "$autostart_dir"
cp -- "$desktop_file" "$autostart_dir/v2rayn-login.desktop"

Before and after copying, check Type=Application and Exec=. If Hidden=true is present, or OnlyShowIn or NotShowIn excludes your desktop, edit the copy in your user directory with a text editor; leave the system file untouched. GNOME may not show a tray icon, so check the process, logs, and listening status instead.

In KDE, you can also search for “Autostart” in “System Settings,” then choose “Add Application” and select v2rayN. Use this method or manual copying, not both. Don’t run a graphical app as a system service: services usually lack a full desktop session, which can cause problems with windows and user configuration paths.

# Remove the login autostart entry created in this guide
autostart_dir="${XDG_CONFIG_HOME:-$HOME/.config}/autostart"
rm -f -- "$autostart_dir/v2rayn-login.desktop"

Troubleshooting: upgrades, startup failures, and lingering proxy settings

Verify the deployment in this order: confirm installation completed in the package manager; launch from the applications menu; check the subscription and core logs; test the local proxy; confirm the target app uses it; then log out and verify autostart. Before upgrading, use the client’s backup feature or save its actual data directory. Subscription links and configuration may contain credentials, so don’t share them in troubleshooting screenshots.