Install v2rayN on Linux: DEB/RPM Setup and Autostart

1. Check your distribution, architecture, and desktop session

Choose a Linux package from the client downloads page. Debian, Ubuntu, and their derivatives generally use DEB packages; Fedora uses RPM. The package format and processor architecture must both match: x86_64 is x64, and aarch64 is ARM64. Don’t guess the architecture based on your computer’s brand.

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

The steps below assume you’re logged in to a graphical desktop such as GNOME or KDE. A command-line-only server has no desktop session, so desktop autostart instructions won’t apply. v2rayN is a graphical client; the proxy core handles connections and forwarding. Installing the client doesn’t enable the proxy by itself.

2. Debian / Ubuntu: Install a DEB and resolve dependencies

Open your Downloads folder in the file manager, then choose “Open in Terminal.” Put the DEB you’re installing in its own directory so the command can’t pick up an older version or another package. Run these commands in Bash: first check that the current directory contains exactly one DEB, then inspect and install it. The variables exist only in the current terminal session.

mapfile -d '' packages < <(find . -maxdepth 1 -type f -name '*.deb' -print0)
if [ "${#packages[@]}" -eq 1 ]; then
  deb_file="${packages[0]}"
  dpkg-deb -f "$deb_file" Package Version Architecture
  sudo apt update
  sudo apt install "$deb_file"
else
  printf 'Leave only the DEB package you want to install in the current directory.\n'
fi

Check the package name, version, and architecture in the output before confirming the installation. The ./ prefix identifies a local file; without a path, apt may interpret the argument as a repository package name. If the architecture doesn’t match, choose the correct package instead of forcing the install.

1. Check package details

   Review the output of dpkg-deb -f to confirm that you downloaded the v2rayN package and that its architecture matches your system.

2. Install and resolve dependencies

   Run sudo apt install "$deb_file". If an earlier dpkg install left packages unconfigured, run sudo apt --fix-broken install and review the proposed changes before proceeding.

3. Check the desktop entry

   After installation, open the app menu and search for v2rayN. Don’t start by adding write permissions recursively to the program directory.

4. Launch as a regular user

   Launch v2rayN as your logged-in user. Once the main window and logs look normal, configure your subscription and login autostart.

3. Fedora: Install an RPM with dnf

As before, open Bash in a directory containing only the package you’re installing. Use rpm -qp to inspect its metadata, then install it with dnf. Querying a local package doesn’t install it and doesn’t require administrator privileges.

mapfile -d '' packages < <(find . -maxdepth 1 -type f -name '*.rpm' -print0)
if [ "${#packages[@]}" -eq 1 ]; then
  rpm_file="${packages[0]}"
  rpm -qp --queryformat '%{NAME} %{VERSION}-%{RELEASE} %{ARCH}\n' "$rpm_file"
  sudo dnf install "$rpm_file"
else
  printf 'Leave only the RPM package you want to install in the current directory.\n'
fi

Don’t use rpm --nodeps to skip dependency checks. The package may appear to install successfully but fail to launch because a shared library is missing. If you hit a dependency error, check the package names and version constraints reported by dnf. If the required version isn’t in your repositories, check that your system version is compatible with the package.

• Package is already installed: Check the installed version; there’s no need to reinstall. To update, download the package for your architecture and let dnf handle the upgrade.
• Can’t read the file: Check the terminal’s current directory and the filename. Don’t run chmod -R 777 on your entire Downloads folder.
• Possible security policy block: Check the actual error and audit logs. Don’t disable SELinux just to open the window.

Installing a local DEB or RPM doesn’t necessarily add a repository for ongoing updates. Whether future upgrades arrive with system updates depends on whether the package configures a repository. If it doesn’t, download and install each new package manually.

4. First launch: Check the listener, then test the proxy

Launch v2rayN from the app menu, import a subscription or node configuration you own, and select an available node. Then check the local listening settings under “Settings” → “Parameter Settings.” The sections may move between versions, so use the port and protocol shown in your current interface.

The examples below assume a local SOCKS or mixed listener on port 10808. This is only an example, not a guaranteed default across all versions. If your port differs, change the number in the command before running it. socks5h lets the proxy resolve the destination hostname, reducing interference from local DNS during this test.

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

• No listening socket found: Check that the core is running, the port is correct, and the logs don’t show a configuration parsing error.
• Connection refused: Usually, nothing is listening at that address and port. Troubleshoot the local listener first.
• An HTTP response was returned: The explicit proxy request received a response from the destination or an intermediary. Check the status code to determine whether the request succeeded.

A website opening in your browser doesn’t mean your terminal automatically uses the system proxy. The curl command above specifies the proxy explicitly and doesn’t rely on desktop proxy settings. For a first-time setup, complete this one-off test before enabling the system proxy or TUN as needed. A regular local proxy doesn’t require running the entire graphical client as root.

5. Autostart at login: Reuse the package’s desktop entry

Here, “autostart” means launching v2rayN after you log in to your graphical desktop—not when the machine powers on, before login. For everyday desktop use, prefer an XDG autostart entry. It reuses the executable path maintained by the package, reducing the chance that an upgrade will break it.

Find the installed desktop file

Run the command below in a regular user terminal. The script copies the file only if it finds exactly one. If it finds multiple files, it lists them and stops. This avoids assuming an install directory or treating the package filename as the launch command.

mapfile -d '' entries < <(
  find /usr/share/applications /usr/local/share/applications \
    -maxdepth 1 -type f -iname '*v2rayn*.desktop' \
    -print0 2>/dev/null
)
if [ "${#entries[@]}" -eq 1 ]; then
  desktop_file="${entries[0]}"
  grep -E '^(Name|Exec|TryExec|Path|Hidden|OnlyShowIn|NotShowIn)=' "$desktop_file"
  autostart_dir="${XDG_CONFIG_HOME:-$HOME/.config}/autostart"
  mkdir -p "$autostart_dir"
  cp -- "$desktop_file" "$autostart_dir/v2rayn.desktop"
  printf 'Copied to: %s\n' "$autostart_dir/v2rayn.desktop"
else
  printf 'Found %s entries; review them manually first:\n' "${#entries[@]}"
  printf '%s\n' "${entries[@]}"
fi

If no entry is found, return to the terminal you used to install the package. Run dpkg-deb -f "$deb_file" Package or rpm -qp --queryformat '%{NAME}\n' "$rpm_file" to get the package name, then use dpkg -L or rpm -ql to list its files. Continue only after confirming the actual desktop entry; don’t guess the program path under /opt.

Check whether autostart is disabled

Open the copied file in a text editor and check the [Desktop Entry] section. If it contains Hidden=true, change it to Hidden=false. If it contains X-GNOME-Autostart-enabled=false, change it to true. You usually don’t need to add these keys if they’re absent. If there’s an OnlyShowIn or NotShowIn entry, make sure it doesn’t exclude your desktop environment.

• Keep the existing valid values for Exec, TryExec, and Path. Don’t change the launch command to sudo without a good reason.
• Exec isn’t an interactive shell, so it won’t expand ~, pipes, or redirections the way a terminal does.
• You don’t need sudo to write to your user’s autostart directory. Using sudo could leave you with configuration files owned by root.
• If you previously enabled autostart in the client, disable one of the methods first to avoid launching the app twice.

6. Verify after logging out, and keep a way to undo it

Save your work and exit v2rayN normally, then log out of your desktop and sign back in. Closing the terminal won’t test login autostart. After signing in, check for the window or process, then check the listening port. Some desktops don’t support tray icons, so the icon’s presence—or absence—isn’t a reliable test.

pgrep -af '[vV]2ray[Nn]'
ss -lntp 'sport = :10808'
journalctl --user -b --no-pager -n 100

Whether startup information appears in user logs depends on the desktop environment. No log entry doesn’t necessarily mean startup failed. If the client is running but a node connection times out, wait for the network to come up, then check your subscription, node, and core logs. Don’t add another autostart entry to fix a network problem.

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

7. Common installation and permission errors

Final verification has three parts: the system package manager can query the package, a proxy request works after launching the client as a regular user, and the listener comes back after you log in to the desktop again. Only when all three pass are installation, connectivity, and autostart complete. Repeat these checks in order after changing ports or upgrading the installation path.