For users installing v2rayN on a Linux desktop for the first time. Choose a package for your distribution and CPU architecture, then launch it as a regular user, import a subscription, and verify the local proxy. Once it works manually, add the same desktop launcher to autostart and check whether your apps pick up the proxy settings in GNOME or KDE.
Choose a Package by Distribution and CPU Architecture
Run cat /etc/os-release in a terminal to identify your distribution, and uname -m to check your CPU architecture. If the output is x86_64, the download may be labeled x64, while DEB metadata often uses amd64. For aarch64, choose the matching ARM64 build. A matching file extension does not guarantee the package matches your architecture or supports your distribution version.
Native Packages
RecommendedChoose DEB for Debian and Ubuntu, or an RPM compatible with your Fedora or openSUSE release. The package manager can resolve declared dependencies and track installed files.
Best for: desktop systems where a matching build is available and the required dependencies are in your configured repositories
Install from an Archive
If an archive is available for your architecture, extract it to a fixed location in your home directory. It may still require system libraries, and you may need to add a desktop launcher manually.
Best for: users who want to manage the application in their home directory and have confirmed that the runtime environment is compatible
DEB and RPM Install Commands
In a terminal, go to the directory containing the package and replace the example filename v2rayN.deb or v2rayN.rpm below with the actual filename. Keep the leading ./ to specify a local file in the current directory. Run only the command for your distribution; there is no need to run all three.
- Debian/Ubuntu:
sudo apt install "./v2rayN.deb"。 - Fedora:
sudo dnf install "./v2rayN.rpm"。 - openSUSE:
sudo zypper install "./v2rayN.rpm"。
If you get an architecture mismatch, return to the download page and choose another package. If dependencies are missing, check the library names and minimum versions in the error, then verify your distribution version and enabled repositories. You can also inspect DEB metadata with dpkg-deb -I "./v2rayN.deb" or view declared RPM dependencies with rpm -qpR "./v2rayN.rpm". Don't force the installation: skipping dependency checks won't provide missing runtime libraries.
First Launch: Desktop Launcher, Subscription, and Listening Ports
Launch the App
Search for “v2rayN” in GNOME Activities or the KDE Plasma application launcher, then open it as a regular user. If it doesn't appear, check whether the package includes a
.desktopfile; don't assume the launch command and application name are the same.Add a Subscription
In the main window, open “Subscription Group” → “Subscription Group Settings,” add a group, enter the subscription URL, and save. If the interface has a “+” button, you can also add a group from the group list. Then update it from the “Subscription Group” menu. If no nodes are available yet, try the update option that doesn't use a proxy.
Select a Node
Switch to the group you just updated, right-click a node, and choose “Set as active server.” Seeing a node in the list only confirms that it was imported. Check the main window log to make sure the core starts and stays running.
Check the Local Ports
Open “Settings” → “Parameter Settings” and check the local listening ports. Confirm whether the current core uses separate ports or a mixed port, then run
ss -ltnto check for the corresponding TCP listener. Leave TUN off during initial testing to keep virtual network adapter issues out of proxy port troubleshooting.
Don't infer the protocol from the port number alone. If the current listener is SOCKS, enter it in the app's SOCKS field; use the HTTP field only for a port that actually supports HTTP. If the log reports that an address is already in use, run ss -ltnp to see listener processes visible to your account. Check whether v2rayN is running twice or another app has the port, then stop the old instance or choose a different port. Update any proxy addresses you entered manually as well.
Autostart: Launch After Signing In to the Desktop
Desktop autostart usually means launching after you sign in to a graphical session, not before the login screen appears. First make sure the app launches from the application menu, then use either the client's built-in autostart option or your desktop environment's autostart settings. Enabling both can launch duplicate instances; a machine waiting at the login screen does not indicate that autostart has failed.
- GNOME: Copy a verified application launcher to your user autostart directory. System launchers are usually in
/usr/share/applications/, while user launchers are typically in~/.local/share/applications/. Create the default autostart directory withmkdir -p ~/.config/autostart, then copy the actual.desktopfile there. If you setXDG_CONFIG_HOME, use theautostartdirectory inside that location. - KDE Plasma: Open “System Settings” and search for “Autostart,” then choose “Add Application” and select v2rayN from the list. Settings categories can vary across Plasma versions, so searching by name is more reliable than looking in a specific category.
- Verify: Sign out and back in, then check for the app window, its process, or a local listening port. If the app launches manually but not at sign-in, check that the user's autostart entry still points to the current executable in
Exec, especially if you've moved an archive or upgraded to a new install path.
System Proxy Settings in GNOME and KDE
GNOME
- Settings
- “Settings” → “Network” → “Network Proxy”
- Mode
- Manual
- Address
127.0.0.1; enter the port for the relevant proxy type
Note your original settings first. If v2rayN can configure the desktop proxy, there's no need to maintain a separate manual configuration.
KDE Plasma
- Settings
- Search for “Proxy” in “System Settings”
- Mode
- Configure the proxy manually
- Address
- Enter the HTTP and SOCKS ports configured by their respective listeners
After saving, test with the app you want to use, especially browsers with their own proxy settings.
A system proxy is a set of settings exposed to apps in the desktop session; it does not route all system traffic. A browser with its own manual proxy setting uses that instead, while terminal tools may read only environment variables or command-line options. If one app works and another doesn't, first check where each gets its proxy settings rather than assuming the node is broken. To proxy only a few apps, leave the desktop's existing settings alone and configure the local proxy in those apps.
Troubleshooting Installation and Autostart
Installed, but why can't I find the app in the application menu?
Check whether the package contains a desktop launcher with dpkg-deb -c "./v2rayN.deb" or rpm -qpl "./v2rayN.rpm", then confirm the installation completed. If the launcher is present but the menu hasn't refreshed, sign out and back in. If the package has no launcher, find the actual executable in the file list and try launching it manually.
No window after signing in—did the app start?
Not necessarily. Check for a local listener first, then see whether the app is set to start minimized. Some desktops don't show a tray icon, so an invisible window doesn't mean the process isn't running. If there is no listener, launch the app from the application menu and see whether the issue occurs only at sign-in.
Can't browse after quitting v2rayN? How do I restore access?
Check whether GNOME or KDE is still pointing to a local port that is no longer running. If so, restore your previous desktop proxy settings; if you weren't using a proxy before, turn off manual proxy mode. If only one browser is affected, check whether it has its own saved loopback address and port.