Choose the operating system for the client, then select a package based on processor architecture and format. Use v2rayN on desktop; for Android, start with v2rayNG and choose v2flyNG only if you need the v2fly core.
For a first install, choose Desktop. It uses a newer cross-platform interface. WPF is the classic, stable Windows edition for users who prefer its familiar layout. Both downloads are ZIP files; choose either one.
After downloading, use File Explorer's Extract All option, then open the installer from the extracted folder. Don't run it from the ZIP preview. If you see a missing runtime message, note the component and architecture mentioned, then follow the requirements for that version. You don't need to switch interface editions first.
Open About This Mac from the Apple menu. If Chip shows an Apple M-series chip, choose Apple Silicon; if Processor shows Intel, choose x64. Both downloads are DMG files, so the extension won't tell you which chip they're for.
Open the DMG in Finder and follow the window's instructions to move the app to Applications. Launch it from there, then eject the disk image when you're done. If it won't open, check whether the issue is an outdated macOS version, an architecture mismatch, or a system security warning. Follow the specific instructions shown; don't disable your device's overall security protections just to launch an app.
v2rayNG uses the Xray core. Most mainstream phones released since 2015 can use arm64, but some devices with 64-bit chips only support 32-bit apps. If you can't confirm which architectures your system supports, choose the universal build. It includes components for multiple architectures and is usually a larger download.
v2flyNG uses the v2fly core. Choose it if your configuration specifically requires that core. Configurations aren't shared automatically between the two clients, so make sure the protocol and transport settings are compatible with your chosen client before importing. The universal build supports more processor architectures; it doesn't add protocol support or change how the client connects.
Choose a package format for your distribution: Debian- and Ubuntu-based systems generally use deb; for distributions that use RPM, check for rpm. Then confirm the architecture: amd64 and x86_64 correspond to x64 here, while aarch64 corresponds to arm64. Even with an Intel processor, you may need the deb marked amd64.
A matching package format doesn't guarantee compatible dependencies. If the installer reports a missing or unavailable library or version, check your distribution and its version first. The rpm filename on this page includes the el10 build tag, so don't assume it works on every RPM-based distribution just because of its extension. Don't force the installation to bypass dependency checks.
Installation, updates, and migration
For a first install, confirm your operating system and architecture. If you need to keep an existing configuration, back it up before installing. If you're downloading a package on this computer for another device, choose based on the receiving device, not the system shown in your browser. The same applies to virtual machines: check the OS and processor architecture inside the VM, not the host computer's brand.
First, check whether you need to update the client or the subscription
Updating the client replaces the app; updating a subscription reloads the configuration from its group address. If a group has unexpected content, try Update subscription first instead of downloading a new client. If menu locations don't match a tutorial screenshot, note the client name, installed version, and interface edition, then find instructions for that version. On Windows in particular, the Desktop and classic WPF editions have different menu layouts; that doesn't mean either one installed incorrectly.
Keep a restorable backup before switching versions
If your current version has an export or backup feature, use the client's built-in option to save your files and make sure you can find the backup. Subscription groups, custom routing, manually added individual configurations, and local ports may not all be stored in the same subscription, so saving just one link isn't a complete backup. Backups may contain private subscription URLs or connection credentials; store them somewhere you control and don't include them with screenshots of an error.
When changing package type, release channel, or device, don't assume you can install over the existing app or reuse its entire data directory. Install the matching package on the target device first, then use the import feature to restore compatible settings. If you customized routes or ports on the old device, compare them one by one on the new device and confirm they work before removing the old configuration.
After the first launch, check these three things in order
First, make sure the window opens. If the app won't start, keep the system message and recheck the package format, processor architecture, and runtime. Don't start changing subscription links or routing rules yet; the app hasn't reached the stage where it reads those settings.
Next, confirm the configuration appears in the list. Adding a subscription address and updating the subscription are separate steps. After adding it, return to the main screen, update, and check the relevant group. If you have a single share link, use an option such as clipboard import rather than treating it as a subscription URL.
Finally, confirm the app is using the connection mode you selected. On desktop, check that the system proxy is enabled and that the target app follows it. On a phone, make sure the client has permission to connect. When testing for the first time, change one setting at a time; changing the port, routing, and connection mode together makes it harder to find the cause of a problem.
When something goes wrong, note the step where it happened, the client name, OS version, selected package architecture, and exact error message. If the browser reports a download error, troubleshoot the download; if the system installer rejects the package, check compatibility; if the app opens but an update fails, check the subscription and network. Separating these stages makes it easier to find the cause than repeatedly downloading the same installer.
Download and installation FAQs
Troubleshoot the issue you're seeing, from choosing the wrong package or an interrupted browser download to an empty list after installation.
Should I install both the Windows Desktop and classic WPF editions?
Install just one. If this is your first time using the client, choose the Desktop edition. Choose classic WPF if you prefer its familiar interface or are following instructions with screenshots of its menus. Before switching, exit the old client and back up its configuration. You can keep both installers, but avoid running both clients at once: if they try to listen on the same local port, the one started later may not work properly, and it may be unclear which client controls the system proxy.
The version on the page doesn't match the number in the download filename. Which should I trust?
The version shown on the card comes from the app listing; the filename reflects the download you selected, so the numbers may differ. Check the installed version in the client's About screen or your system's app details. If you need a specific version, verify the file you downloaded and the information shown by the installer or system. If you still can't confirm it, don't assume the page's version number applies to that file, and don't rush to overwrite your existing installation.
Android says “App not installed.” Should I try the universal build?
If the error points to an architecture mismatch, check which architectures your system supports, then try the universal build. If it reports a conflict with an existing package, switching to the universal build usually won't help. First check available storage, the Android version, and the full error message. Then check whether a client with the same name is already installed and whether both builds came from the same release channel. Uninstalling may remove subscriptions and settings, so back up your data before deciding whether to reinstall.
What should I check if a download is interrupted or the file won't open?
Check whether the browser's download list says the download is complete, then verify the file extension and selected platform. Fully extract Windows ZIP files before opening the installer; open macOS DMG files in Finder; use the system installer for Android APKs; and use the appropriate package manager for Linux deb or rpm files. If the download is incomplete, retry it in your browser. If you keep getting an error page, note the selected download link and the browser message. Don't change the file extension and mistake an error page for an installer.
Why can't I see any subscriptions after installation?
The installer only installs the client; it doesn't add subscriptions. In v2rayN, add the address under Subscription Groups, then update. In v2rayNG, open Subscription Group Settings, save the address, return to the main screen, and update subscriptions. If the list is still empty, check the selected group, make sure the link is complete, and confirm the subscription is valid before troubleshooting connection settings. Never post a full, private subscription URL in a public forum.