Linux Installation and Autostart

Check Your Distribution and Architecture

v2rayN is a desktop client for managing nodes, subscriptions, and core processes. DEB and RPM are package formats; they do not determine which protocols a node uses. Whether a VMess or VLESS node works also depends on the selected core, transport settings, and server configuration. Check your system before installing—changing package formats will not fix protocol errors.

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

Choose the Linux installation instructions and the package for your architecture on the client download page. This guide avoids hard-coding version numbers and package filenames, which can change with updates. The commands below are written for Bash. When prompted, enter the actual path to the downloaded file. Paths containing spaces are supported; do not add quotes when entering the path.

Install a DEB or RPM Package with Your Package Manager

When installing a local package, use your distribution's package manager to resolve dependencies. Ubuntu and Debian use apt install; Fedora uses dnf install. If your software repositories are unreachable, dependency resolution may fail. Fix repository connectivity first rather than forcing an install that ignores dependencies.

1. Find the Package Path

   Locate the downloaded file in your file manager and copy its full path. Enter the path in the terminal, then use the commands below to check the package name, version, and architecture. Make sure the package matches your distribution.

2. Install the Package

   Run only the command group for your distribution. Review the dependency changes listed by the package manager before confirming. If the plan would remove many desktop components, cancel and check for mixed or conflicting repositories.

3. Launch v2rayN for the First Time

   Open v2rayN from your desktop's application menu. Use administrator privileges for installation and a regular user account for everyday use—don't confuse the two. Keep the window open initially and make sure the core starts without errors before setting up autostart.

Ubuntu / Debian: Install the DEB Package

read -r -p 'Enter the full path to the DEB file: ' pkg
pkg="$(realpath -- "$pkg")"
dpkg-deb -f "$pkg" Package Version Architecture
sudo apt install "$pkg"

Use an absolute local path to tell apt to install the file from your disk, rather than search the repositories by package name. If a previous dpkg -i command left packages unconfigured, run sudo apt --fix-broken install and review the proposed changes before confirming. Don't routinely force installs that ignore dependencies.

Fedora: Install the RPM Package

read -r -p 'Enter the full path to the RPM file: ' pkg
pkg="$(realpath -- "$pkg")"
rpm -qp --queryformat '%{NAME} %{VERSION}-%{RELEASE} %{ARCH}\n' "$pkg"
sudo dnf install "$pkg"

Test the Connection Before Setting Up Autostart

A successful installation only confirms that the program files are in place. On first launch, add a subscription or import a node, then select a node and test the connection. Menu groups can change between versions; common options are “Subscription Group” → “Subscription Group Settings,” followed by an update from the “Subscription Group” menu. If the labels differ in your version, follow the menu as it appears—don't look for a button with the same name in another platform's client.

Go to “Settings” → “Parameter Settings” to check the local listening port and type. 10808 is an example for testing, not a guaranteed default in every version. The commands below assume a SOCKS or mixed inbound on that port; check it against your actual configuration before running them. First verify that the port is listening, then make an explicit proxy request without relying on desktop system proxy settings.

ss -ltnp 'sport = :10808'
curl --proxy socks5h://127.0.0.1:10808 \
  --connect-timeout 5 --max-time 15 \
  --head https://example.com/

• Nothing is listening: Check the core logs, make sure a node is selected, and look for startup errors. Don't change the desktop proxy settings yet.
• Port already in use: Check whether another client instance is using it. Stop the duplicate instance, or change the listening port and update the test command to match.
• The request returns an HTTP response: The explicit proxy request succeeded. The status code doesn't have to be 200; check it against the target site.
• The command works but the browser doesn't: Check the browser and desktop proxy settings. Not every Linux application reads the same system proxy configuration.

socks5h sends the destination hostname to the proxy for resolution. This reduces reliance on local name resolution for this test, but a single request can't prove that system-wide DNS or all application traffic is routed as expected.

Choose an Autostart Method

The desktop client depends on a user session. For everyday desktop use, XDG autostart is a better fit than a system-level service. It takes effect when you log in to the graphical desktop; it won't run the client before the login screen. Choose one of the two methods below to avoid starting duplicate instances at login.

If your v2rayN version already offers and has enabled an autostart option, check which entry it created before choosing the manual method in this guide. Don't keep entries created by the client, desktop settings, and a manual copy at the same time. The client continuing to run in the system tray after you close its window doesn't mean autostart is configured for your next login.

Create an Autostart Entry You Can Inspect

Find the .desktop file installed by the package rather than assuming the program is in a particular directory. The queries below work for DEB and RPM packages. Enter the package name you found during installation. In the output, look for the main v2rayN launcher under /usr/share/applications/.

Find the Desktop Launcher

# Ubuntu / Debian
read -r -p 'Enter the deb Package field: ' package
dpkg -L "$package" | grep -E '/applications/[^/]+\.desktop$'

# Fedora: run this group on Fedora only
read -r -p 'Enter the rpm NAME field: ' package
rpm -ql "$package" | grep -E '/applications/[^/]+\.desktop$'

Use desktop-file-edit below to edit the launcher keys. On Ubuntu or Debian, run sudo apt install desktop-file-utils; on Fedora, run sudo dnf install desktop-file-utils to install the required tools. Then copy the file as a regular user—don't add sudo to the commands below.

read -r -p 'Enter the full path to the installed desktop file: ' source
test -f "$source" && grep -E '^(Name|Exec|TryExec|DBusActivatable)=' "$source"

autostart_dir="${XDG_CONFIG_HOME:-$HOME/.config}/autostart"
target="$autostart_dir/v2rayn-login.desktop"

mkdir -p "$autostart_dir"
cp -- "$source" "$target"

desktop-file-edit \
  --remove-key=Hidden \
  --remove-key=OnlyShowIn \
  --remove-key=NotShowIn \
  --remove-key=DBusActivatable \
  --set-key=X-GNOME-Autostart-enabled --set-value=true \
  "$target"

desktop-file-validate "$target"

Before copying, make sure the query points to the intended program and that Exec= contains a valid launch command. This keeps the package's Exec command, removes desktop environment restrictions, and launches the command directly rather than relying on D-Bus activation. If the original file includes TryExec, that program must also exist or the desktop may skip the entry.

• User directory: If XDG_CONFIG_HOME isn't set, the destination is ~/.config/autostart/v2rayn-login.desktop.
• Path rules: Exec= isn't an interactive Shell. Don't replace the original launcher with a command that uses ~, $HOME, or a pipe.
• Executable permissions: XDG autostart usually doesn't require the desktop file to be marked executable. A file manager's “Allow Launching” prompt is a separate interaction.
• Updates: A copy in your user directory won't be updated with the package. If an upgrade changes the launcher path, copy the file from the new package and check it again.

No output from the validation tool usually means the file passed the format check, but it doesn't guarantee that the program will run. After saving, exit the client normally, log out of the desktop, and log back in. Reopening the terminal alone won't test login autostart. After logging in, wait for the desktop to load, then check the window, system tray, and local port to confirm that only one instance started.

Troubleshoot Dependencies, Permissions, and Login

Upgrade and Remove Autostart

When upgrading, use the local installation command for your distribution and exit the running client first. Installing a new version usually doesn't remove user settings, but back up the data directory you actually use before upgrading—especially subscription groups, routing rules, and custom settings. Check the current version's settings or logs to find the directory; the program's installation directory isn't necessarily where all its data is stored.

To stop v2rayN from launching at login, you don't need to uninstall it. Delete the autostart file created in this guide. If you also have an entry in desktop settings or one created by the client, disable it there too. Removing autostart won't stop a process that's already running.

autostart_dir="${XDG_CONFIG_HOME:-$HOME/.config}/autostart"
rm -f -- "$autostart_dir/v2rayn-login.desktop"

• After upgrading, launch the app manually from the desktop menu and make sure it can read your settings and start the core.
• Check the listening port again to make sure an old process isn't still using it and being mistaken for a problem with the new version.
• If you keep autostart enabled, check whether the new package changed its desktop launcher. Recreate the user copy if needed.
• Finally, log out and back in to verify autostart, then test the browser's proxy settings separately.