Choose your operating system, then confirm the CPU architecture. Download links are grouped by package format. If the device already has a configuration, export a backup before upgrading.
The classic, stable edition retains the familiar Windows interface. Choose it if you already have an established workflow.
The download is a ZIP archive. Extract it fully to a writable folder, then run the installer inside. Don’t launch it from the archive preview.
Installation and switching editions
Desktop and WPF mainly differ in UI technology and layout; they aren’t separate proxy protocols. Configure subscriptions, outbounds, and routing based on the capabilities of the core in use. Don’t judge protocol support by the window’s appearance. If a field is missing, check compatibility with your client and core versions.
Close v2rayN before installing, and check the taskbar notification area to make sure it isn’t still running. If the old client still has configuration files open, the upgraded version may load settings that haven’t been saved. Before switching editions, export your configuration and restore it using the new version’s import feature. Avoid overwriting one version’s entire program folder with another.
After the first launch, import a subscription and confirm the server settings before enabling the system proxy. The system proxy only affects apps that follow system proxy settings; it doesn’t route every program. If a browser connects but another app doesn’t, check whether that app uses the system proxy before trying another traffic-routing method.
macOS installers
Use the v2rayN Desktop edition. Apple Silicon and Intel Macs have separate download links; don’t choose based on the computer’s appearance or purchase year.
Choose the x64 installer for a Mac that shows an Intel processor in About This Mac.
Open the DMG and follow the instructions in the window. Before launching for the first time, make sure the app has been copied to the Applications folder—not launched from the mounted disk image.
First launch and network settings
On first launch, macOS may show a prompt about the app’s source or permissions. Read it carefully and follow the options available in System Settings. On managed devices, follow your organization’s device policies; don’t disable system-wide security to launch the app. If macOS says the app can’t run on this computer, check the chip architecture and OS version first.
After importing an existing subscription, confirm that the client can read the configuration before enabling a proxy mode. Changing the system proxy may affect browsers and other apps that use system network settings. If you already have a manual proxy or another network tool configured, note the original settings and avoid changing them at the same time. If you still can’t connect after closing the client, check for a leftover proxy address in system network settings.
When moving from another desktop OS, sync your subscription first, then migrate routing and DNS settings one at a time. A subscription link mainly carries server settings; it won’t necessarily copy all local preferences. Recheck settings tied to file paths, network interfaces, and permissions on the new device.
Android APKs
We recommend v2rayNG, which uses the Xray core. Choose v2flyNG if you need to keep using a V2Fly-compatible configuration. Each client manages its own settings.
Most mainstream phones released since 2015 are likely to support arm64, but the OS must also support 64-bit apps. If you can’t confirm the architecture, choose the universal version. Don’t rely solely on the processor specs advertised for your phone.
A good fit for configurations that use Xray protocols and related transport security options. After importing, check that fields such as VLESS and REALITY are present and complete.
For configurations that are already compatible with V2Fly. The same guidance applies when choosing between arm64 and universal. Before switching clients, make sure the required protocols and transport settings are supported by the relevant core.
Don’t assume Xray-specific settings can be used interchangeably. To compare protocol support, see the Core family guide →
System requirements and installation permissions
Check
Before installing
If you run into trouble
OS and architecture
Android; arm64 packages require support for 64-bit apps
If you’re unsure of the architecture, try the universal version. Check the installer for the minimum OS version.
Package format
APK, installed by the device’s package installer
Make sure the download is complete and grant installation permission to the browser or file manager you’re using
Network permissions
VPN mode requires system approval
Check whether another app is already using the VPN connection
In-place upgrade
Keep the signing channel consistent for the same app
If signatures conflict, back up your data before uninstalling the existing app
Installation, permissions, and background activity
When you open the APK, Android may ask you to allow app installs from the current browser or file manager. Grant permission only to the source you’re using, and check afterward whether it still needs access. If the installer reports that the app wasn’t installed, first distinguish an architecture mismatch, an unsupported OS version, or a signature conflict. Don’t repeatedly download and install the same package.
The version shown on the v2rayNG page may temporarily differ from the package name because the manifest maintains the version field and download link separately. Check the version shown by the installer and the client’s About page to confirm what was installed. Don’t manually change the number in the package name to match the page, or guess a different download URL.
On the first connection attempt, Android displays a system VPN permission prompt. This lets the client route device traffic according to its rules; it doesn’t confirm that the server settings are correct. Import a subscription, select a configuration, and start the service, then verify the connection using logs and an app. If another VPN service is already active, decide which app should handle the connection first.
Background disconnections and installer architecture are usually separate issues. If the connection drops when the screen turns off, check battery optimization, background activity limits, and system cleanup settings. Configure per-app proxying to match your needs, and avoid routing apps that only need local access. Mux isn’t a general-purpose battery-saving switch.
Linux packages
Use the v2rayN GUI client. Choose deb or rpm based on your distribution, then confirm whether your device is x64 or arm64.
amd64 and x86_64 usually refer to the same 64-bit x86 architecture; arm64 and aarch64 refer to 64-bit ARM. Choose the package that matches your device.
Dependency checks and desktop proxy settings
After downloading, open the package in your distribution’s graphical software installer so the package manager can check dependencies and conflicts. Consider the target distribution in the rpm filename when checking compatibility; don’t force installation just because your system uses rpm. If dependencies are missing or a core library version doesn’t match, check the system and package requirements rather than skipping dependency checks.
Installing the client doesn’t automatically route desktop traffic through a proxy. Desktop sessions and apps can handle system proxy settings differently. Configure a working outbound in the client first, then check whether the target app follows the desktop’s proxy settings. Browsers, background services, and standalone network apps may need to be tested separately.
If you need traffic routing, read the relevant permission guidance first. Don’t run the entire client as an administrator long-term just to launch its GUI. Before upgrading, export the configuration and keep custom routing, DNS, and local path settings. After restoring, check that permissions and file locations are still valid.
Configuration steps before and after installation
The installer determines the program and architecture. Connecting also depends on server settings, protocol compatibility, and the local proxy mode.
01 / BACKUP
Back up before upgrading
Keep subscription groups, manual servers, routing rules, DNS, and UI preferences. Saving only subscription links usually won’t restore all local settings. Backups may contain connection credentials; store them securely and don’t upload them to public forums.
02 / IMPORT
Import an existing configuration
The client installer doesn’t include server settings. Import them from a subscription, share link, or configuration backup, then check the address, port, protocol, and transport security fields. Successful import only means the format was recognized; it doesn’t confirm that the remote server is available.
03 / VERIFY
Check which traffic will be routed
Choose an outbound before enabling the system proxy or VPN mode. Test with the target app, then review DNS, handshake, and routing results in the logs. A “started successfully” message alone doesn’t confirm that app requests followed the expected rules.
From choosing a package to the first launch, distinguish architecture, signing, runtime, and configuration issues.
Desktop or classic WPF: which v2rayN version should you choose?
For a first install, start with the Desktop edition, which uses a next-generation cross-platform interface. Choose the classic, stable WPF edition if you prefer its familiar interface or need to keep an existing workflow. Both are v2rayN; don’t enable the system proxy in both. Back up your settings before switching.
Android: arm64 or universal APK?
Most mainstream phones released since 2015 are likely to support arm64, but confirm that the OS supports 64-bit apps. If you’re unsure of the architecture or the arm64 installer reports incompatibility, try the universal version. It includes components for multiple architectures; it won’t make your connection faster.
The client’s displayed version doesn’t match the installer filename. Which should I trust?
The displayed version and download link come from separate manifest fields and may temporarily be out of sync. Don’t infer package contents from the displayed version or edit the download path manually. Check the version shown by the system installer, then confirm the installed version on the client’s About page.
What should I back up before upgrading?
Export the client configuration first, including subscription groups, manual servers, routing rules, and DNS settings. Close the old client before upgrading. On Android, use the same installation source and signing channel where possible. If you see a signature conflict, back up your data before taking any further action; don’t uninstall the app right away.
Can I connect through a proxy as soon as installation is complete?
The installer provides the client, not a ready-to-use server configuration. Import an existing subscription or valid server settings, choose an outbound, and set the proxy mode. If the connection fails, check the address, port, protocol, and transport security fields first, then review the logs.
The installer says the app can’t be installed. What should I check first?
Check the OS, CPU architecture, package format, and system version, then make sure the download is complete. On Windows, fully extract the ZIP before opening the installer. On Android, check installation permissions and signing conflicts. On Linux, check distribution dependencies. On macOS, review the system security prompt and follow your organization’s or device’s policies.