Install v2rayN on Linux: DEB/RPM Packages and Autostart

Before you install: Check your distribution, architecture, and package format

DEB and RPM are package formats, not proxy protocols. Debian and Ubuntu generally use DEB packages; Fedora uses RPM. The fact that both target Linux doesn’t mean you can install an RPM with apt. Converting package formats to work around distribution differences isn’t recommended either. When you visit the download page to choose a Linux package, check that it matches your CPU architecture.

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

The uname -m command typically outputs x86_64 for x64 or amd64 packages, and aarch64 for arm64 packages. Package names don’t always use the same architecture labels as system tools, so check the package metadata. If the installer reports an architecture mismatch, choose a compatible package instead of forcing it to ignore the check.

DEB and RPM: Install with your package manager

Run these commands in a Bash terminal. You’ll enter the package path interactively, so there’s no need for a fixed version number or made-up filename. Enter the full absolute path; paths containing spaces work without extra quotation marks. The variables in the commands are already quoted. Check the package metadata before installing, then review the transaction to avoid installing the wrong file from your downloads folder.

Install a DEB package on Debian or Ubuntu

read -r -p 'Enter the absolute path to the DEB file: ' package
if [ -f "$package" ]; then
  dpkg-deb -f "$package" Package Version Architecture
  sudo apt update
  sudo apt install "$package"
else
  printf '%s\n' 'File not found. Check the path.'
fi

apt install resolves dependencies from your configured repositories. If dependencies can’t be satisfied, first check your distribution version, repository status, and the package requirements. Don’t add repositories from another distribution or use force-overwrite options to replace core system libraries. If a previous dpkg -i command left packages unconfigured, you can run sudo apt --fix-broken install. Review the proposed installation or removal list before confirming.

Install an RPM package on Fedora

read -r -p 'Enter the absolute path to the RPM file: ' package
if [ -f "$package" ]; then
  rpm -qp --queryformat '%{NAME} %{VERSION}-%{RELEASE} %{ARCH}\n' "$package"
  sudo dnf install "$package"
else
  printf '%s\n' 'File not found. Check the path.'
fi

First launch: Verify the local proxy before configuring the desktop proxy

After launching the app, import a subscription. A subscription provides node configuration; the installer doesn’t generate one. VMess, VLESS, and other protocols are connection protocols, not DEB or RPM installation options. The selected core must support the protocols, transports, and security settings in your subscription. Don’t change its ports, transport paths, or TLS settings just to clear an error.

1. Add a subscription

   In the main window, open “Subscription group” → “Subscription group settings,” add a group, and enter a valid subscription URL. Save it, then use the “Subscription group” menu to update that subscription. Button labels may vary slightly between versions; follow the labels in your app.

2. Choose a node

   After the update, select an entry in the node list and choose “Set as active server” from the right-click menu. Check the logs to confirm the core starts successfully. A node appearing in the list doesn’t mean it’s reachable.

3. Check the listening port

   Open “Settings” → “Parameter settings” and check the local listening address, port, and inbound type. The examples below use a SOCKS inbound manually set to 127.0.0.1:10808. For your tests, use the values shown in your app.

4. Configure the proxy

   Run the command-line test below before configuring the desktop proxy. In GNOME, the setting is usually under “Settings” → “Network” → “Network Proxy” → “Manual.” In KDE Plasma, it’s usually under “System Settings” → “Network” → “Proxy.” The exact menu grouping varies by desktop version.

ss -lntp | grep ':10808'
curl --proxy socks5h://127.0.0.1:10808 \
  --connect-timeout 15 --max-time 30 \
  -I https://v2rayhk.com/

The first command checks for a TCP listener. The second explicitly sends a request through the SOCKS proxy and resolves the destination hostname through the proxy. This is a connection test, not a speed or anonymity assessment. If your inbound is HTTP, use the corresponding HTTP proxy address; don’t enter a SOCKS port in the desktop’s HTTP proxy field. App support for desktop proxy settings varies, and terminal tools may not use those settings.

Desktop autostart: Copy the existing launcher

Graphical clients generally depend on a user session. To have the client appear automatically after startup, set it to launch at desktop login rather than creating a root system service. The standard approach is to copy the .desktop launcher provided by the package to the current user’s ~/.config/autostart/ directory. Keeping the original Exec entry avoids guessing the executable path.

Find and copy the launcher file

find /usr/share/applications "$HOME/.local/share/applications" \
  -maxdepth 1 -type f -iname '*v2rayn*.desktop' -print 2>/dev/null

read -r -p 'Enter the full path to the desktop file you found: ' entry
if [ -f "$entry" ]; then
  grep -E '^\[Desktop Entry\]|^(Name|Exec|TryExec|Hidden|OnlyShowIn|NotShowIn|X-GNOME-Autostart-enabled)=' "$entry"
  mkdir -p "$HOME/.config/autostart"
  cp -- "$entry" "$HOME/.config/autostart/v2rayn.desktop"
  chmod 644 "$HOME/.config/autostart/v2rayn.desktop"
else
  printf '%s\n' 'Launcher file not found. Check that the installation is complete.'
fi

Before copying, make sure the destination doesn’t contain custom settings you need to keep; the command above overwrites any autostart entry with the same name. If your search returns no results, check the launcher properties in the applications menu or locate the file using the package file list. Don’t invent an unverified Exec=v2rayN entry. Use dpkg-deb -c to list DEB contents or rpm -qpl to list RPM file paths.

• Check the [Desktop Entry] section in the copy. Hidden=true disables the launcher; in GNOME, X-GNOME-Autostart-enabled=false may disable it too. To enable the launcher, edit existing keys in this section rather than blindly appending duplicates at the end of the file.
• OnlyShowIn and NotShowIn restrict which desktop environments can use a launcher. If it’s limited to another desktop, check why before editing your copy.
• A standard autostart file only needs read permissions; 644 is sufficient. Don’t run chmod 777 on the entire directory.
• After saving, log out and back in to verify. Check that the client is running, then confirm the core and network are ready. A tray icon alone doesn’t prove the proxy is working.

To stop autostarting, delete the copy in your user directory: rm "$HOME/.config/autostart/v2rayn.desktop". This won’t uninstall the app. If autostart is also enabled inside the client, check whether it manages the same file to avoid maintaining two launch entries. Desktop autostart doesn’t automatically enable the system proxy; that depends on the client’s saved settings and your desktop environment.

Troubleshoot dependencies, permissions, and login startup

Troubleshoot from local to remote: Can the app run? Does the core start? Is the port listening? Does a proxy request succeed? Is the app using the proxy? This separates installation problems from unreachable nodes and desktop proxy settings, so you can fix the actual issue instead of reinstalling without changing anything.

Before upgrading, exit the client and keep your current user configuration. Install the new package with the same package manager, then check that the applications menu launcher and the autostart copy still have matching Exec entries. Uninstalling a package usually doesn’t remove all user configuration or manually copied autostart files, so check ~/.config/autostart/ after uninstalling too. For other connection issues, follow the steps in Troubleshooting.