macOS · Windows · Linux · Android clients

V2Ray for macOS client downloads v2rayN subscriptions and proxy setup

Download v2rayN View setup guide

Choose a free, open-source client and follow the English menu labels to import subscriptions and configure system proxy and routing.

Subscription groups System proxy Routing & TUN
4desktop and mobile platforms
3graphical clients
2core families
GPL-3.0 open-source license Xray-core · v2fly-core

Follow the menu paths to configure proxy and routing

Import a subscription and select a server first. Then choose how app traffic enters the client and which rules handle it. The interface below is a static setup illustration, not a live view of your device.

Three system proxy options

Open the tray menu and choose “Set system proxy automatically” to let apps that follow system proxy settings, such as browsers, use the local proxy. “Clear system proxy” removes the system proxy settings, while “Do not change system proxy” leaves them as they are—it does not turn the proxy off. This makes it easier to switch settings centrally than to configure each app separately, but it will not route every app automatically. If your browser uses its own proxy extension, resolve any conflicting settings first. Clear the system proxy before quitting the client to prevent apps from trying to connect to a local port that is no longer open.

PathTray menu → Set system proxy automatically

Routing rules and global proxy

Open “Routing” from the tray menu. Start with a preset to understand how traffic is handled, then edit the rules as needed. Rules can match domains or destination addresses and use outboundTag to select an outbound. They are generally evaluated in order, so put specific matches before broad ones. A global preset controls how traffic that reaches the core is routed; it does not automatically proxy apps that never pass through the client. Save your existing configuration before making changes. When testing, change one condition at a time so routing, DNS, and server issues are easier to distinguish.

PathTray menu → Routing

Subscription groups and keyword filters

Open “Subscription group settings” and enter a label and subscription URL for each source. Save, then update subscriptions. Labels are for local reference and do not change provider information. Keyword filters narrow the server list; they do not test whether a server works. Grouping subscriptions by source makes it easier to find update failures, duplicates, and plan changes than keeping every server in one list. Subscription URLs may contain access credentials, so do not include them in public screenshots. If the list is empty after an update, check the URL and filters first, then try updating through the proxy if needed.

PathSubscription groups → Subscription group settings

TUN mode and administrator privileges

Consider TUN mode when you need to handle traffic from apps that ignore system proxy settings. It routes traffic through a virtual network interface and still requires appropriate routing and DNS settings; it is not simply a “global” switch. When enabling it for the first time, follow the system prompts and check the platform, core, and permission requirements. TUN can affect more of your network than the system proxy, so watch for conflicts with other virtual adapters, remote access, or proxy tools. Note the switch state while testing. If the network stops working, disable TUN first, then check whether basic connectivity has returned.

PathMain window → TUN mode

Choose a traffic mode that fits your apps

Start with the least intrusive settings to verify the connection, then expand the traffic being routed. Switch between the options below to see whether your apps follow system proxy settings.

Start by testing in a browser

For your first setup, start with the system proxy. Import a subscription, select a server, and enable “Set system proxy automatically.” Then test a site in a browser that follows system proxy settings. If something goes wrong, check the client logs and local listening port instead of immediately adding TUN, a separate browser proxy extension, or multiple routing rules. Once the browser works, check whether other apps use the same system settings. This sequence helps separate server connection problems from app routing issues and makes changes easier to undo.

Read the system proxy setup steps →

Choose a client and installer

Choose v2rayN for desktop, or v2rayNG or v2flyNG for mobile depending on your core requirements. Check your processor architecture before opening the matching download page.

macOS

Use v2rayN to manage subscriptions and proxy settings. Open “About This Mac” from the Apple menu: models that show “Chip” usually need the Apple Silicon build; models that show an Intel processor need the Intel build. Don’t rely on the computer’s appearance or purchase year. After downloading, follow the installation instructions to move the app to Applications, then launch it from there so it remains available after the disk image is ejected.

If macOS blocks the app on first launch, verify the download source and system requirements, then check the prompt under “System Settings → Privacy & Security.” For regular browser use, start by configuring the system proxy; handle the required permissions separately if you need TUN. Installation and authorization are separate steps: installing the client does not route all app traffic through the proxy.

Go to downloads

Windows

Choose the v2rayN desktop edition or the classic WPF edition. The desktop edition uses a cross-platform interface and suits users who want a similar workflow across computers running different operating systems; WPF retains the classic Windows interface. Check the requirements for each download separately. Don’t assume that menu locations or runtime requirements for one edition also apply to the other.

Before installing, check the system type under “Settings → System → About” and review the runtime requirements on the download page. After launching, import a subscription, select a server, and configure the system proxy. If your browser cannot access the web after you quit the client, check whether the system is still pointing to a local proxy port. Reinstalling usually does not remove leftover proxy settings.

Go to downloads

Android

Start with v2rayNG, which uses the Xray core. If an existing configuration depends on V2Fly behavior, compare it with v2flyNG. Most newer devices use the arm64 build; if you’re unsure of the architecture, check the universal build notes. The package architecture determines whether the app can install and run; the core determines which configuration features it supports. Don’t confuse the two.

Import a subscription, select a server, start the connection, and approve Android’s VPN connection request. This differs from the desktop system proxy, so there is no need to follow the Mac tray menu steps. If the connection drops when the app moves to the background, check battery optimization and background activity restrictions. If another VPN app is running, check whether it has replaced the connection.

Go to downloads

Linux

Choose v2rayN, then select the package format (deb or rpm) and architecture (x64 or arm64). Both must match; the file extension alone is not enough. Your desktop environment, display server, and package dependencies can also affect startup, so check the system requirements on the download page and in the installation guide before installing.

After launching, check that the graphical interface works, subscriptions update, and a regular proxy connection succeeds before configuring the desktop environment’s system proxy. Some apps do not read desktop proxy settings and need separate configuration or a different traffic routing mode. Before enabling TUN, check permissions and virtual network adapter requirements. If something goes wrong, restore regular network access, save the error logs, and check dependencies and routes one at a time.

Go to downloads

To get started, you also need a working server configuration or subscription URL. The client reads configuration, launches the core, and provides the interface; installing it does not create a service you can connect to. Once you have your service details, follow this order: install → import a subscription → select a server → configure the proxy → verify access. This makes it easier to identify where something went wrong.

Browse all clients → Browse the complete setup guide for all platforms →

Understand open-source clients and cores

Know the difference between the interface, the core, and the service configuration. Similar names do not mean their functions are interchangeable.

Project V ecosystem V2Fly / Xray cores Graphical clients and configuration

From Project V to two core families

Project V is a useful starting point for understanding the V2Ray ecosystem. In everyday searches, “V2Ray” may refer to a proxy core or more broadly to the clients and configurations built around it. V2Fly continues community development of V2Ray, while Xray grew from related code into a separate core family. They share some technical background, but their features and configuration support are not identical. When reading a guide, first check which core it covers; fields with the same name or similar menu options do not guarantee compatibility.

The core handles protocols, routing decisions, and network connections. The graphical client provides subscription management, server lists, logs, and controls. The service provider supplies remote addresses and connection parameters. Each layer has a different role. A successful subscription update only means the client retrieved and parsed the configuration; selecting a server does not mean the system proxy is enabled. Testing each layer separately is more effective than repeatedly changing every setting.

Choose a core for your configuration needs

VMess, VLESS, and Trojan are connection protocols; features such as REALITY and XTLS Vision also depend on specific implementations and configuration requirements. A server name alone does not establish compatibility, and a successful import does not guarantee a working connection. Check the server-side requirements against the available client cores and their support. Before migrating, keep the original configuration and test one entry. Confirm the protocol, transport, security settings, and DNS behavior before moving the full subscription group.

v2rayN is a desktop client that organizes configuration in a graphical interface and uses the corresponding core. v2rayNG is for Android and uses the Xray core; v2flyNG offers an Android option based on the V2Fly core. All three are open-source projects, but their features are not interchangeable. If you use the same subscription across devices, check which core each device runs and which configuration fields it supports rather than comparing client names alone.

Separate open-source licenses from service terms

All three clients are released under the GPL-3.0 open-source license. The license sets the terms for using, modifying, and redistributing the code; it is not the terms of service for a remote proxy service and does not determine which provider to use. A free client and a paid subscription are separate things. Review the software license, service plan, and applicable network conditions independently. The client download page is not a place to obtain server accounts.

Open-source software does not, by itself, define the privacy boundaries of your device. Subscription URLs may contain identifiers, configurations may store server addresses and credentials, and logs may record destinations and error details. Share only the necessary excerpts when troubleshooting, and hide subscription URLs and credential fields in screenshots. If you receive an unfamiliar configuration, verify its source before importing it; don’t load a complete configuration from an unknown source just to fix a connection.

Handle software and subscription updates separately

Updating the client, updating the core, and updating a subscription are separate operations. A client update changes the interface and configuration management; a core update may change protocol support or network behavior; a subscription update fetches the server configuration published by your provider. Change one layer at a time and keep settings you can roll back to. This helps identify whether an issue comes from a software change, a subscription change, or the current network. The download page lists available installers; the home page explains how to choose and configure them.

Before upgrading, note your subscription groups, routing choices, system proxy setting, and TUN state. After upgrading, test the basic connection before restoring custom rules. If an old configuration behaves differently in the new environment, check the logs and the relevant feature guide instead of immediately replacing all your settings. The menu locations shown on this page illustrate the workflow; the actual interface may vary by client version. If you can’t find an option, check the relevant platform section in the installation guide.

Read configuration and troubleshooting guides

Find practical steps for subscription management and connection problems alike.

Browse all articles →