Install v2rayN on Linux: DEB/RPM Packages and Automatic Startup

1. Check Your Distribution, Architecture, and Install Method

v2rayN is a desktop client. A successful installation does not guarantee a working connection: you'll also need a valid server configuration or subscription and a core that supports the selected protocol. This guide covers installing the client in a graphical desktop environment; it does not configure a system proxy service to run without a logged-in user. These desktop autostart steps aren't suitable for a headless server.

Open a terminal and run these two commands. The first shows your distribution and version; the second shows your system architecture. In most cases, x86_64 corresponds to an x64 package and aarch64 to an arm64 package. Installing missing dependencies won't fix an executable that doesn't match your architecture.

cat /etc/os-release
uname -m

2. Install a DEB Package on Ubuntu or Debian

For a local DEB file, use apt install rather than running dpkg -i alone. apt can fetch declared dependencies from your configured repositories. Run the commands below in Bash. When prompted, enter the actual path to the downloaded file. If the path contains spaces, enter it as is—don't add quotes around it.

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

1. Check the Package Details

   Review the Package, Version, and Architecture values in the output above. If the command can't read the file, make sure you entered the path to a downloaded DEB package, not a webpage or compressed archive.

2. Review the Installation Plan

   Review the packages apt proposes to install, upgrade, or remove. If it plans to remove a large number of desktop components, cancel and check whether your repositories mix different distributions or versions.

3. Launch from the App Menu

   After installation, search for v2rayN in your desktop's application menu and launch it as a regular user. Installing software requires elevated privileges; running the graphical client does not.

4. Keep the Error Output

   If no window appears, find the desktop launcher installed with the package and check its Exec field. Then run the corresponding command in a terminal and note any missing libraries or permission errors.

If running dpkg -i left the package unconfigured, try sudo apt --fix-broken install and review the proposed changes before confirming. It may install missing dependencies or remove packages with unresolved dependencies, so don't assume it will keep the client installed. If your repositories can't be reached, restore access before trying the installation again.

3. Install an RPM on Fedora and Find the Launcher

On Fedora, use dnf to install a local RPM. It resolves dependencies using your system repositories; rpm -i alone does not fetch missing dependencies. First enter the actual file path, then inspect the package metadata, and finally install it.

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

Don't add options to skip dependencies or force an overwrite just because you see a dependency conflict. Missing shared libraries, a package for the wrong architecture, and mixed repository versions are different problems—use the specific package names shown in the terminal to identify the cause. An RPM package isn't necessarily compatible with every RPM-based distribution.

The desktop launcher is your reference for troubleshooting and autostart. If its Exec line contains desktop field codes such as %U or %F, don't copy them as regular command-line arguments when testing in a terminal. Use the actual paths in the package, and don't make the entire installation directory writable by every user.

4. First Connection: Subscription, Port, and System Proxy

On first launch, keep the regular proxy mode and leave TUN disabled. In the main window, open “Subscription Group” → “Subscription Group Settings,” add a group, and enter the subscription URL. Save it, then select “Update” from the “Subscription Group” menu. Menu names may vary slightly by version; use the group settings window and update menu as your guide. Subscription URLs may contain credentials, so redact them in terminal screenshots and support requests.

After selecting a configuration as the active server, open “Settings” → “Parameter Settings” to check the local listener details, then confirm the actual listening address in the client log. The examples below use port 10808; your version or existing configuration may use a different port. Use the matching curl command only after confirming that the port supports HTTP or mixed proxy connections.

ss -ltnp 'sport = :10808'
curl --proxy http://127.0.0.1:10808 --max-time 15 -I https://example.com

If you have a dedicated SOCKS port, change curl's proxy option to --proxy socks5h://127.0.0.1:10808 and adjust the port to match your configuration. socks5h resolves the destination hostname through the proxy. An HTTP response confirms that this explicit proxy request got a response; it doesn't mean every app on your system is using the proxy.

• Nothing is listening locally: Check the core startup log, configuration parsing errors, and port conflicts before changing browser settings.
• Explicit proxy works, but the browser doesn't: Check the client's “System Proxy” menu and your desktop's network proxy settings. Some apps don't use the desktop proxy.
• Terminal traffic still connects directly: Terminal apps usually don't inherit the graphical desktop's proxy settings. Test with the app's own proxy options instead.
• Planning to enable TUN: Back up your routing and DNS settings first, then configure permissions for your version. Don't launch the entire desktop app as root just to test the regular proxy.

5. Missing Tray Icon or No Window

GNOME, KDE Plasma, and other desktops handle tray support differently. If the tray icon is missing in GNOME, v2rayN may still be running; the desktop may lack status indicator support, or an installed extension may not be enabled. First try reopening the window from the app menu, then check the process and local listening status.

If the app opens and connects successfully but the tray icon is missing, fix desktop integration rather than reinstalling the core. If the log shows that the core process exited, troubleshoot the configuration and core permissions instead. A tray extension can't fix protocol errors or port conflicts.

6. Start v2rayN at Login with the Desktop Launcher

What people call “startup at boot” is more accurately “start after desktop login” for the v2rayN graphical client. The graphical session isn't ready when the computer powers on before login, at a text-only terminal, or through a remote command session. Most desktop environments support the XDG autostart directory ~/.config/autostart/. Reusing the desktop file provided by the package is more reliable than guessing the Exec path.

1. Confirm It Works Manually

   Launch the app from the application menu and complete a connection test first. If the client has its own autostart option, check whether it has already created an entry so you don't configure a duplicate.

2. Find the Desktop Launcher

   Use the package file list from the previous section to find the app's desktop file. Check its Exec path and confirm it isn't an uninstall entry or pointing to a temporary download directory.

3. Copy It to Your User Directory

   Run the command below and enter the full path to the desktop file. The destination is fixed as v2rayN.desktop to make it easy to check and remove. This affects only your current user.

4. Verify After Logging Back In

   Save your work, then log out and back into the desktop. Check the client process, window, or tray icon, then verify the local port and connection. Don't rely on the icon alone to confirm autostart worked.

read -r -p "Enter the full path to the app desktop file: " entry
grep -E '^(Type|Exec|TryExec|Hidden|OnlyShowIn|NotShowIn)=' "$entry"
install -Dm644 "$entry" "$HOME/.config/autostart/v2rayN.desktop"

Read the grep output before copying: Hidden=true disables the autostart entry, while OnlyShowIn and NotShowIn limit which desktops can use it. If the app doesn't start after copying, check these fields in a text editor and look for X-GNOME-Autostart-enabled=false. Changing the Name field alone won't help: it only changes the display name and doesn't launch the app.

To undo this setup, delete only the file you created in this section. If there's another v2rayN autostart entry in your system settings, check and disable it too so it doesn't look like removing the file had no effect.

rm -- "$HOME/.config/autostart/v2rayN.desktop"

7. Upgrade and Restart Checklist

Upgrading a package with the same name usually lets apt or dnf replace the program files. User configuration, the autostart copy, and desktop proxy settings are managed separately. Exit the client and back up the configuration directory actually in use before upgrading. Check the current version's settings or logs for its location; don't delete the entire user configuration tree.

• Launch: Open the new version from the app menu. If the launcher no longer works, compare its Exec path with the updated package file list.
• Autostart copy: Compare the installed desktop file with ~/.config/autostart/v2rayN.desktop. If the program path has changed, copy the updated file and keep any user settings you need.
• Connection settings: Check the active server, subscription group, and routing selection to make sure the upgrade hasn't selected a different configuration.
• Local listener: Run ss with the actual port, then test an explicit proxy request. If the listener works but the remote connection fails, check the connection log rather than reinstalling the package.
• On exit: Check the desktop's network proxy settings after closing the client. If they still point to a local port that's no longer open, clear the system proxy or restore your previous network settings.

Verify everything in order: launch the app manually, confirm the explicit proxy works, test the apps you need, then log out and back in to check that the client starts correctly. Checking all four steps makes issues easier to pinpoint than simply looking for a tray icon after startup. For subscription import and setup, see the Getting Started guide. For advanced routing and DNS changes, see Advanced Configuration.