Desktop uses a modern cross-platform interface and is the best choice for a first install. WPF is the classic, stable version for users familiar with the older interface and menus. These are two alternative versions, not a main app and a patch—choose one.
Before Installing on Windows
Windows System Requirements
Item
How to check
System type
Go to Settings → System → About and confirm that you have a 64-bit system with an x64 processor.
Runtime
If startup reports a missing .NET desktop runtime, check the required version and architecture in the prompt.
Unzip location
Extract all files to a separate folder your account can write to, then launch the app.
Check the full entry under “System type.” Seeing “64-bit operating system” alone isn’t enough; it doesn’t tell you whether the processor is x64 or ARM. Both builds here are x64. If your device uses a different architecture, don’t choose based on “64-bit” alone.
When switching interfaces, test the new version in a separate folder. Don’t extract both builds to the same location. Keeping the old folder helps you tell whether the new version failed to launch or an old setting caused migration trouble. After the first launch, make sure the main window and system tray work before importing a subscription. There’s no need to enable the system proxy or launch at startup yet.
If no window appears after you double-click the app, check whether it’s already running in the system tray, then look for a runtime warning from Windows. If the error says the app can’t write to its folder, move it to your Documents folder or another writable location. Don’t make running as administrator part of your routine.
Open the Apple menu and choose About This Mac. If it says Apple chip, choose Apple Silicon; if it says Intel processor, choose Intel. These are builds of the same client for different architectures—not different memory or storage options.
Before Installing on macOS
macOS System Requirements
Item
How to check
Chip
Choose arm64 for Apple silicon and x64 for Intel processors.
macOS version
Check your version in About This Mac. The minimum requirement depends on the release you choose.
Install location
Open the DMG and follow the window’s instructions to move the app to Applications.
A DMG is a disk image used to distribute apps. Once installation is complete, launch the app from Applications, not from the mounted image. That way, you can eject the image and keep using the installed copy.
When moving to a new Mac, choose a build for its chip. You can back up interface preferences and subscription groups separately; there’s no need to copy the app files. If the app says it can’t run on your system at first launch, check the chip and macOS version. Reimporting a subscription won’t fix a compatibility issue.
On a managed device, app installation and network settings may be controlled by an administrator. Note the exact system message and distinguish between “can’t open the app” and “can open the app but can’t change proxy settings.” Check installation requirements for the first; check permissions and existing network settings for the second.
Most phones released since 2015 support arm64; check that your device supports arm64-v8a. If you’re not sure, choose the universal build. It supports multiple architectures and is usually larger—not faster.
Choose this alternative if your existing configuration specifically requires the V2Fly core. It isn’t an update to v2rayNG. After switching, check that your configuration imports and that its protocol and transport settings are supported.
Before Installing on Android
Android System Requirements
Item
How to check
Architecture
Check that your device supports arm64-v8a; if you’re unsure, choose the universal build.
macOS version
Check your Android version under About phone and confirm it meets the selected client’s release requirements.
Install permission
Manage permission to install apps from unknown sources per app. Managed devices may block installation.
After downloading, open the APK from your browser’s download history or a file manager. If Android says apps can’t be installed from this source, check that the named source is the app you’re using to open the file. You don’t need to grant permission to other apps. Install permission is separate from the VPN permission requested when you first connect.
If an update fails to install over an existing version, first tell whether the message says the package conflicts with an existing app or the device is incompatible. The former is often related to the installation source or signing; a universal build usually won’t help. For incompatibility, check the architecture and Android version. If you need to uninstall the old version to switch sources, back up subscriptions and manually added configurations first—uninstalling may also remove local data.
Before connecting for the first time, check whether another app is using the system VPN. Stop any connection you don’t need so you can confirm the new client takes over correctly. Once the test succeeds, adjust per-app proxy settings one at a time so you can separate installation issues from routing changes.
Debian and Ubuntu users typically choose DEB. On RPM-based distributions, check that the package matches your system. The RPM filename here includes el10; don’t assume it will install on your distribution based on the file extension alone.
Before Installing on Linux
Linux System Requirements
Item
How to check
Architecture
Check your system information for x86_64 or aarch64, then choose the matching build.
Distribution
Check that the package format matches your distribution and version. Don’t mix formats.
Desktop environment
This is a GUI client and requires a desktop session that can launch graphical apps.
The processor architecture determines whether the app can run; the distribution determines whether the package fits your system. Check both independently. For example, two systems may both report x86_64 but use different package management systems, so they can’t necessarily use the same installer.
Open the matching package in your desktop software installer, review the dependency prompts, then confirm installation. If dependencies are missing, check which components are needed and whether your distribution’s repositories provide compatible versions. Don’t ignore dependency errors: installation may appear to finish, but the GUI still might not launch.
A window opening on first launch confirms that the GUI client is running; it doesn’t mean other apps are using the proxy. For your next test, choose an app that clearly uses the desktop proxy settings and compare its behavior before and after connecting. Some apps use their own network settings, which you’ll need to check separately.
From Installation to Your First Connection
Check the download before setting up your configuration
After clicking Download, check your browser’s download history to confirm the file is complete. Don’t open a temporary file that’s still being written. Filenames may include the client, architecture, package format, and release version; check the client and architecture first. The version shown on the card comes from the app listing and may not match a number in the filename. When recording the installed version, use the one shown after launching the client.
If a button opens the wrong page, return to the platform section and make sure you clicked the installer, not a platform tab. Then check whether the download hasn’t started, was interrupted, or completed. The first two are download issues; if it completed but won’t open, check the system requirements, package format, chip, and OS version. Troubleshoot each stage separately instead of downloading several builds in a row.
Keep a recoverable copy of your settings before updating
Before updating, note your current subscription groups, routing mode, and custom settings. If the client has an export or backup feature, save a copy somewhere you can access. A server’s display name alone isn’t enough: names can be duplicated and can’t be used to reimport a configuration. Don’t share backups containing subscription URLs or connection details in public comments, screenshots, or support tickets.
After updating, check that your groups are still there, then test a configuration that worked before. If neither the old nor new version connects, check your local network and subscription status first. If only the new version has issues, compare its mode, permissions, and routing options. To roll back, restore your backed-up settings; don’t mix app files and data folders from different versions at random.
Test connections and routing in order
After installation, open the setup guide and follow the steps in order: import a subscription, select a configuration, enable the appropriate mode, and test access. The client’s connection status and an app’s actual ability to access a site are different signals. The latter also depends on the app, routing rules, and DNS resolution.
For your first test, keep the default settings and use just one app and one configuration. Once the basic connection works, see the advanced guide for groups, routing, and DNS settings. When making changes, note what you changed, which apps you expect it to affect, and how to undo it. If something goes wrong, revert the most recent change and test the same app again; there’s no need to reinstall the client and change every variable at once.
Download and Installation FAQs
Do I need to install both the Windows Desktop and WPF versions?
No. Choose Desktop for a first install; choose WPF if you prefer the classic interface or want to keep your familiar workflow. Back up your settings and exit the old client before switching.
How do I check which chip my Mac has?
Open the Apple menu and choose About This Mac. If it says Apple chip, choose the Apple Silicon build; if it says Intel processor, choose the Intel build.
Will the Android universal APK fix every installation issue?
No. A universal APK is worth trying when you’re unsure of your device’s architecture, but installation can still fail if Android is too old, the signature doesn’t match, or device policies block it. Check the system message before switching builds.
Does amd64 on Linux work only with AMD processors?
No. amd64 and x86_64 both refer to the same 64-bit x86 architecture, supported by compatible Intel and AMD devices. For ARM devices, choose the arm64 or aarch64 build.
Why is the server list empty after installation?
The installer includes only the client. Add a subscription URL or configuration that you’re authorized to use, follow the setup guide to import it, then select a profile and test the connection.