Use deb packages on Ubuntu and Debian, and rpm packages on Fedora. Administrator privileges are needed only for installation. Launch v2rayN as your regular desktop user, verify the local proxy, then enable the system proxy and autostart at login. This guide includes install commands, port checks, and troubleshooting steps for apps that launch from the menu but not at login.
Choose a Linux package: distro and CPU architecture
Identify your Linux distribution first, then your CPU architecture. Run these two commands in a terminal: the first shows your distribution and version; the second shows your machine architecture. Ubuntu and Debian package metadata usually labels x86_64 as amd64 and aarch64 as arm64. Fedora package metadata usually uses x86_64 and aarch64. The x64 option on the download page refers to the first architecture.
cat /etc/os-release
uname -m
Debian-based packages
- Desktop distributions
- Ubuntu、Debian
- File extension
.deb- Package architecture
amd64orarm64- Package manager
apt
Use apt to install the local package and resolve any dependencies available from your configured repositories.
Fedora packages
- Desktop distributions
- Fedora
- File extension
.rpm- Package architecture
x86_64oraarch64- Package manager
dnf
The rpm format alone doesn't guarantee compatible dependencies. Check package compatibility separately for other distributions.
If the error explicitly reports an architecture mismatch, return to the download page and choose the correct package; don't force the installation. If the architecture matches but a library is missing, note the first unmet dependency and its version, then check your distribution's repositories and version. Don't install a same-named library from a different distribution.
Install commands for deb and rpm packages
Run only the section for your distribution. When prompted, paste the absolute path to the package you downloaded; don't add quotes. The double quotes in the install command preserve spaces in the path. Check the package metadata first to confirm its name, version, and architecture, then run the installation command with sudo.
Ubuntu and Debian: install a deb package with apt
printf 'Enter the absolute path to the deb package:'
IFS= read -r pkg
dpkg-deb -f "$pkg" Package Version Architecture
sudo apt install "$pkg"
If the terminal reports that dependencies couldn't be downloaded, first make sure your system can reach its repositories with the proxy turned off. Then run sudo apt update and try again. If the proposed installation would remove existing desktop components, cancel and check for mixed distributions or repository versions.
Fedora: install an rpm package with dnf
printf 'Enter the absolute path to the rpm package:'
IFS= read -r pkg
rpm -qp --queryformat '%{NAME} %{VERSION}-%{RELEASE} %{ARCH}\n' "$pkg"
sudo dnf install "$pkg"
After installation, search for “v2rayN” in your desktop's application menu. A package manager confirming installation only means the files are installed; it doesn't confirm that the GUI or core is running. If there’s no menu entry, note the package name found above. On Ubuntu or Debian, run dpkg -L followed by the package name; on Fedora, run rpm -ql followed by the package name. These commands show the package's .desktop file and installation paths.
First launch: permissions and system proxy checks
Launch v2rayN as your regular desktop user. Leave TUN disabled for now, and don't run the GUI with sudo. Administrator privileges are needed to install the software, but usually not to access your personal settings or run a local proxy. If the startup log shows Permission denied, check whether the error refers to a user configuration file or the core executable. Don't recursively loosen permissions on the entire installation directory.
Select the current node
If you already have a configuration, select a node in the main window's list, right-click it, and choose “Set as active server.” If this is a fresh install and the list is empty, add a subscription under “Subscription groups” and update it. Then check the main window log for core startup errors.
Check the listening port
Open “Settings” → “Parameter settings” and check “Local listening port” and the local inbound settings. Field names may vary between versions. Use the port shown in the app; don't enter the remote port of a node server as the local port.
Test the local proxy
First, route a terminal request explicitly through the local proxy. This helps distinguish core connectivity issues from desktop proxy settings. The command below uses
10808as an example mixed inbound port. If your version uses separate HTTP and SOCKS inbounds, adjust the protocol and port to match your settings.Set the system proxy
Open “System proxy” from the bottom of the v2rayN main window or the tray, then choose “Automatically configure system proxy.” In GNOME, check the result under “Settings” → “Network” → “Network Proxy.” If the desktop settings haven't changed, try configuring the target app to use its own proxy instead of repeatedly restarting the core.
ss -ltn 'sport = :10808'
curl --max-time 15 -I --proxy socks5h://127.0.0.1:10808 https://example.com/
The first command only checks whether the local TCP port is listening. The second confirms that the request reached the target site through the specified proxy only if it returns the site's HTTP response headers. If the connection to the local port fails immediately, check the port and core logs. If the port is listening but the request times out, check the active node, network, and routing. If your browser works but the terminal doesn't, that doesn't mean the installation failed: many terminal apps don't use the desktop proxy settings. Configure a proxy separately for each app as needed.
Start v2rayN automatically when you log in to Linux
On desktop Linux, autostart usually means launching after you log in to your graphical session, not before the login screen appears. First confirm that v2rayN opens from the application menu, then choose one of the methods below. Duplicate autostart entries can launch the app multiple times at login and make it harder to disable or troubleshoot.
Autostart from desktop settings
RecommendedIn KDE Plasma, open “System Settings,” search for “Autostart,” then choose “Add” → “Add Application” and select v2rayN from the list. If Ubuntu's application menu includes “Startup Applications,” choose “Add” and enter the verified command that launches the app. Menu labels may vary by desktop version.
Best for: desktops with an autostart manager, where you want to enable or disable startup in the GUI.
User-level XDG autostart entry
Find the .desktop file used by the application menu in the installed package's file list, then copy it to your user's autostart directory. Keeping the original Exec= command is safer than guessing the installation path based on another machine.
Best for: desktops that follow the XDG autostart standard but don't offer a convenient GUI option.
To use a file-based entry, run the command below in a terminal and enter the absolute path to the confirmed .desktop file when prompted. Don't use sudo. Unless you've customized XDG_CONFIG_HOME, the autostart directory is ~/.config/autostart.
printf 'Enter the absolute path to the installed .desktop file:'
IFS= read -r desktop_file
autostart_dir="${XDG_CONFIG_HOME:-$HOME/.config}/autostart"
mkdir -p "$autostart_dir"
cp -i -- "$desktop_file" "$autostart_dir/"
Log out and back in without opening v2rayN manually first. Once the desktop has loaded, check the tray, window, or local listening port. If the window appears but web traffic isn't using the proxy, check the system proxy setting again: launching the app and configuring the proxy are separate steps. To undo file-based autostart, remove only the copy in your user's autostart directory; the application menu entry will remain.
Linux installation and autostart troubleshooting
Installed, but nothing happens when you click the menu entry?
Check what Exec= in the package's .desktop file points to. You can also run command -v v2rayN to see whether that name is in your search path. If it isn't, use the package file list to find the actual executable, then run it from a terminal as your regular user and read the error. If a shared library is missing, investigate the library name and your distribution version instead of relaunching the app with administrator privileges.
Starts manually, but not after you log in?
Make sure you're logging in with the account that was used to add the autostart entry. Then open the .desktop file in that user's home directory and check for Hidden=true, OnlyShowIn, or NotShowIn restrictions. If you recently upgraded the package, compare the copy's Exec= path with the file currently used by the application menu.
Logs say the port is already in use?
Run ss -ltnp 'sport = :10808' to check the example port; replace the number if you're using a different one. First, quit any duplicate v2rayN instances. If another running app is using the port, change the local listening port under “Settings” → “Parameter settings,” and update any browser or terminal proxy settings you configured manually.
Browser stops loading pages after you quit v2rayN?
If you enabled automatic proxy configuration, choose “Clear system proxy” under “System proxy” before quitting. If you've already quit, restore the previous setting in your desktop's network proxy settings. Also restore the browser's own settings if you configured a proxy there manually. Otherwise, the browser may keep trying to connect to a local port that is no longer listening.