Top desktop pick v2rayN · Xray / sing-box

V2Ray Mac Client Download v2rayN and set it up

Download v2rayN View the guides

Choose a client for your platform, from importing a subscription to configuring the system proxy and TUN mode.

Free and open source Setup guides Subscription and routing management

Subscriptions, system proxy, and routing

Understand how the settings fit together before changing anything. The interface below is a read-only illustration.

View the full documentation →

v2rayN is the graphical interface for managing configuration; the core handles connections and applies rules. A subscription supplies server details to the client. The system proxy determines which apps send requests to the local proxy, while routing determines whether those requests connect directly or go through a remote server. These are separate steps: updating a subscription won't fix a system proxy, and changing routing won't make every app follow the system's network settings.

For your first setup, import one subscription group, select one server, then enable the system proxy and test access in a browser. This makes it easier to see the effect of each change. Enabling TUN, changing DNS, and adding custom rules all at once makes connection issues much harder to diagnose. Interface labels may vary by platform; check your installed client for the exact settings.

v2rayN · Configuration Settings

Subscription groups and updates

A subscription URL is an updatable list of servers, not a client installer. Open the subscription group settings, enter a label and URL, save, then update the group and select a server from the server list. Grouping subscriptions by purpose helps keep personal settings separate from subscription settings. v2rayN and v2rayNG both support subscriptions, but they handle native configurations differently, so check the format before importing. If an update fails, check the request error and verify the URL before deleting local groups. Subscription URLs may contain access credentials, so don't post them publicly.

Enable subscription updates
Group actionsUpdate current subscription
Import fromSubscription URL / share link
Learn about subscription formats →

Choose a V2Ray client for your platform

Use v2rayN on desktop. For Android, start with v2rayNG and consider v2flyNG if you need its core.

Browse all clients →

Windows

 Top desktop pick

v2rayN comes in Desktop and classic WPF editions. Desktop uses a cross-platform interface, while WPF keeps the classic desktop experience. Check your operating system and runtime requirements before choosing; there's no need to install both clients for the same subscription.

After installation, make sure the client starts and the core runs before importing a subscription. If the app closes immediately, check runtime and permission messages before changing server settings. If you're migrating an existing setup, back up your subscription URL and custom routing rules first.

Go to downloads

macOS

 v2rayN

On a Mac, check About This Mac for the chip type. Apple Silicon uses arm64; Intel processors use x64. After downloading and installing, follow the system prompts to open the app for the first time, then configure your subscription and system proxy. If macOS blocks the app, check its source and the system alert first.

For everyday browsing, start with automatic system proxy configuration. If a command-line tool doesn't use the proxy, check its network settings separately. Set up TUN only if you need to cover more apps, and review its permissions, DNS, and routing behavior first. There's no need to enable every feature at the outset.

Go to downloads

Android

 v2rayNG / v2flyNG

v2rayNG uses the Xray core and suits configurations that need its protocols and transport features. v2flyNG uses the V2Fly core and is an alternative when that core is required. Most phones use arm64; if you're unsure of your processor architecture, check the universal package details.

After importing a subscription, update the group, select a server, and approve the system connection request. Background operation may be affected by battery management. If the connection drops after running for a while, check both battery-saving settings and network changes. Avoid running both clients at the same time to prevent them from competing for the system network connection.

Go to downloads

Linux

 v2rayN

Choose deb or rpm for your distribution, then select x64 or arm64. The package format must match your system's software manager, and the processor architecture must match your hardware. Check desktop environment, dependencies, and permission requirements before installing.

Linux desktop environments don't all handle system proxy settings the same way. If a browser connects but other apps still connect directly, check whether those apps read the desktop proxy settings. Set up the virtual interface and permissions only if you need TUN; don't mistake a network manager issue for a failed subscription.

Go to downloads

Three steps to configure v2rayN before connecting

Verify a single connection first, then add routing rules or TUN settings.

Read the full guide →
Step 1 · Prepare your configuration

Import and update a subscription

The client doesn't provide remote servers to connect to. Get a valid subscription URL or share link, save it in the subscription group settings, then update the group. If you have just one link, use the clipboard import option if your client supports it; a regular webpage URL isn't a subscription URL.

After the update, check that the expected servers appear in the server list. If the list is empty, check the subscription format, expiration, and update logs. Query parameters in the URL may be used for authentication, so keep them intact when copying. Hide them in screenshots before sharing.

Step 2 · Choose an exit route

Select a server and configure the system proxy

Select a server from the list and make it the active choice, then confirm that the core starts successfully. On desktop, set the system proxy to configure automatically and choose a routing preset that suits your needs. On Android, start the connection using the client's workflow and approve the system network connection prompt.

Direct and proxy routes are exit policies; they don't indicate whether a server is online. Keep settings simple for your first test. If another network tool is running, stop one of the tools and test again to avoid confusion from multiple proxy layers.

Step 3 · Check what is covered

Check the app and connection logs

Use an app known to follow the system proxy to access a service, then check the client logs for the corresponding connection. Being able to open the client doesn't mean requests are reaching the core; connecting to one website doesn't mean every app uses the same route.

If something goes wrong, check the subscription, server, core, system proxy, and DNS in that order. Change one setting at a time and note the result. Once a regular connection is stable, you can configure TUN, local network access, or more specific rules; this also makes it easier to undo changes.

When saving your configuration, note the server source, core, and purpose of any custom rules. Subscription updates usually change the server entries in a group, and manual edits may not be retained. If you need to maintain a configuration long term, manage it separately after checking how your client handles updates. When you leave the current network or finish testing, check that the system proxy has been restored—especially before closing the client.

Don't reinstall the client as your first response to a connection failure. Check whether the error is from a subscription request, core startup, or remote handshake, then troubleshoot the relevant area. Logs may contain subscription URLs, server domains, or identity fields; remove sensitive details before sharing them. See the setup guide for steps, or the full documentation for platform-specific installation and permissions.

Project V, V2Fly, and Xray

Distinguish the ecosystem, core, and client to know which program should use a configuration.

Compare clients →
Project V · proxy tools ecosystem
V2FlyXraysing-box · independent core project
v2rayN · desktop configuration interfacev2rayNG · Android / Xrayv2flyNG · Android / V2Fly

Ecosystem names and protocol names are different things

Project V is the ecosystem behind a range of proxy tools and components, with V2Ray as one of its best-known names. Different core and client projects have since emerged in the community, so searches for “V2Ray client” often turn up V2Fly, Xray, and v2rayN as well. These names refer to different layers: protocols describe how communication works, cores implement protocols and routing, and graphical clients help manage subscriptions, settings, and runtime status.

How V2Fly, Xray, and sing-box differ

V2Fly continues community development of V2Ray. Xray grew from related technical foundations and has developed its own protocol implementations and features. sing-box is a separate proxy core project. Their features overlap, but their native configuration formats and supported features aren't identical. Even when names like VMess, VLESS, or Trojan match, check the transport layer, security settings, and how the client generates the configuration. A matching protocol name doesn't guarantee that the full configuration is interchangeable.

What the three open-source clients do

v2rayN, v2rayNG, and v2flyNG all provide their client code as open source. v2rayN is for desktop and brings subscriptions, system proxy, routing, and core operation together in one interface. v2rayNG is for Android and uses the Xray core; v2flyNG is another option built around the V2Fly core. Open source means the code can be inspected and used under its license; it doesn't mean all projects share the same license. Check each project's terms separately.

Client and subscription updates are separate

Updating the client addresses interface, compatibility, and application features. Updating the core affects protocol implementation and runtime behavior, while updating a subscription refreshes remote server details. Rule databases may have their own update process as well. Record your current settings and back up your configuration before upgrading. Afterward, verify your existing connection before trying new features. When troubleshooting compatibility, note the client, core, and server settings—not just that “V2Ray isn't working.”

When choosing a client, start with your device platform, then check the protocols and core required by your server, and finally make sure the workflow suits your needs. Mac users can usually start with v2rayN's subscription and system proxy features; mobile connections are managed with Android clients. These downloads and guides explain how to configure the tools. They don't provide subscriptions or replace the provider's information about accounts, data limits, or server availability.

Understand terms such as REALITY, Vision, DNS, and GeoSite in their respective technical layers. REALITY is a connection security setting; Vision is a related flow-control mechanism; DNS affects name resolution; and GeoSite matches domain collections. Changing one won't automatically fix problems elsewhere. Keep a working baseline, then expand the setup one change at a time using logs and comparison tests. This is usually easier to maintain than copying an unfamiliar configuration wholesale.

V2Ray configuration guides

From system proxy settings to rule databases, find the guide for the issue you're working on.

Browse all articles →