Open-source client · Download and setup

V2Ray Starter GuideDownload and set up v2rayN

From importing subscriptions to configuring routing, follow practical setup steps for desktop and Android clients.

VMess
VLESS
Trojan
REALITY
Shadowsocks

v2rayN

Servers / Subscription groups / Routing

Settings preview

Servers

Subscription groups

Routing

Settings

Subscription groups

＋

AllDefault group

Server filter (regex)

Hong Kong|Japan

↻ Update subscription (without proxy)

Routing

＋

RulesPresetsAdvanced

geosite:cn→direct
geoip:private→direct
geosite:category-ads-all→block

Automatically configure system proxy
Enable TUN
Allow connections from the local network

Subscriptions Routing TUN mode DNS settings Switch cores

v2rayN Core Settings

Organize subscriptions first, then decide where traffic should go. Change one type of setting at a time and keep a rollback option.

Subscription / Filter

Group by source and filter by name

Hong Kong|Japan
(?i)hongkong|japan
^(?!.*test).*$

Subscription groups separate sources, while server filters narrow the current list. Give each group a recognizable name, then add the subscription URL. Once the update succeeds, use “Hong Kong|Japan” to match either keyword in a server name. Case sensitivity can be handled with inline syntax, but support varies by client. If the filter returns no results, clear the expression before considering deleting the subscription. Groups preserve source information and make future updates and troubleshooting easier than importing servers one by one. Subscription URLs may contain access credentials, so hide the full link before sharing screenshots or logs.

Routing / First Match

Put specific rules first and catch-all rules last

{
  "routing": {
    "rules": [
      {
        "type": "field",
        "domain": ["geosite:category-ads-all"],
        "outboundTag": "block"
      },
      {
        "type": "field",
        "ip": ["geoip:private"],
        "outboundTag": "direct"
      }
    ]
  }
}

Routing rules are evaluated in order, so a broad condition near the top can override a more specific one below. First decide what should connect directly, what should be blocked, and what should use a proxy, then create the corresponding rules in the GUI. This snippet is only a configuration fragment; the referenced direct and block outbounds must already exist. It cannot run as a complete configuration on its own. Domain groups depend on geosite data, and address groups depend on geoip data. A rule can still prevent startup if the required data file is missing, even when its name is correct. Unlike simply switching global modes, routing rules preserve local network access and let different destinations use different outbounds.

Traffic / TUN

Test the system proxy before routing all traffic

Automatically configure system proxy: enable it and test first
Enable TUN: turn it on only when needed
DNS interception: configure it to match your setup
Allow connections from the local network: enable only when needed

A system proxy serves apps that respect the system proxy settings. TUN uses a virtual network interface to capture a wider range of traffic. First confirm that the subscription and selected server work in standard proxy mode, then grant the required permissions and enable TUN. After startup, check access from your browser, target apps, and local network devices. Avoid running multiple tools that capture network traffic at the same time. TUN does not send every connection through the same outbound; routing rules still determine where traffic goes. Compared with setting a proxy separately in each app, TUN is better suited to handling apps that ignore system proxy settings, but DNS must be checked too.

DNS / Resolution

Treat DNS resolution and connection routing as separate steps

{
  "dns": {
    "servers": ["localhost"]
  }
}

DNS translates domain names into addresses; routing decides which outbound a connection uses. They interact, but they are not the same setting. This snippet uses a local resolver to illustrate the configuration structure, not to prescribe a setup for every network. Before using it, check that the resolver is reachable, which route its queries take, and whether the core supports the selected format. With encrypted DNS, also consider how the resolver's hostname is resolved initially. Checking each step in the resolution path is more likely to reveal dependency loops than simply swapping one server address. If a domain fails to open but its IP address is reachable, start by checking the DNS logs.

Core / Compatibility

Choose a core based on protocol requirements

Client GUI → generates configuration
Proxy core   → handles connections and routing
Rule databases → classify domains and IP addresses

The GUI client manages subscriptions and generates configuration; the core handles protocols, resolution, and traffic forwarding. Available cores and switching options in v2rayN vary by release, so check the options in your current version. For requirements such as REALITY, first confirm that the subscription parameters are compatible with the target core, then switch and review the startup logs. Do not mix configuration fields from different cores or assume similarly named features work identically. A GUI is easier for everyday settings than editing an entire configuration by hand. For custom outbounds, consult the manual for field names, tags, and rule references.

Client / Platform

Choose a client for your platform

Use v2rayN on desktop and start with v2rayNG on Android. The download page lists package formats and processor architectures separately.

Windows

v2rayN · Top pick for desktop

A good fit for desktop users who need subscription groups, system proxy settings, and detailed routing. The download page offers a desktop edition with a newer cross-platform interface and a WPF edition that retains the classic interface. They are two interface options for the same client; you do not need to install both to use a proxy.

Check your processor architecture in system settings before choosing a download. After the first launch, import a subscription, select a server, and confirm that the standard system proxy works before trying TUN. If the client opens but your browser cannot connect, check that the system proxy points to the address and port the client is actually listening on. Reimporting the same subscription will not fix a proxy setting mismatch.

Before switching interface editions, back up your subscription groups and routing settings, and note your current configuration. Do not let two clients modify the system proxy at the same time. When troubleshooting is done or you are ready to quit, check that the proxy settings have been restored as expected so apps do not keep trying to connect to a stopped local port.

Go to downloads

macOS

v2rayN · Choose by processor

For managing subscriptions, routing, and proxy modes from one desktop interface. Open “About This Mac” to check the processor: choose the arm64 download for Apple Silicon or x64 for Intel. Do not guess based on the computer's appearance or purchase date; match the package to the actual hardware.

If a system security warning appears on first launch, verify the installer source, then follow the instructions under “Privacy & Security.” Network access, system proxy settings, and virtual network interfaces involve different permissions. A working standard proxy does not mean TUN permissions are set up. Follow the prompts in the current interface one at a time; this is usually more effective than reinstalling repeatedly.

When moving a configuration from another computer, import the subscription first, then check local ports, rule files, and path settings. Absolute paths from the old device may not work on the new one. If macOS blocks the first launch, follow the platform guide to check security prompts and network permissions in order; there is no need to change system security settings wholesale.

Go to downloads

Android

v2rayNG recommended · v2flyNG alternative

v2rayNG uses the Xray core, while v2flyNG uses the V2Fly core. Both are open-source GUI clients. Choose based on the protocols and parameters in your subscription and the app settings you need—not on similar names. Most recent phones use arm64. If you are unsure of the architecture, check the device information before trying a universal package.

When you connect for the first time, Android will ask for permission to establish a VPN connection. This uses Android's VpnService API; you do not need to enter a separate VPN configuration in Android settings. Allow only one app to capture network traffic at a time. If the connection drops after running in the background, check battery optimization, background activity limits, and the device manufacturer's autostart settings.

To proxy traffic from only selected apps, first check whether the per-app list is set to include or bypass mode. Select the target apps, then reconnect. Whether an app is captured and which outbound its traffic uses are separate questions: the first depends on the capture scope, while the second depends on routing rules. For full instructions, see the Android platform guide.

Go to downloads

Linux

v2rayN · Choose a package for your distro

For desktop users who want to manage subscriptions and routing through a GUI. The download page offers deb and rpm packages for x64 and arm64. Check your distribution's package format, then confirm the machine architecture. Package compatibility and core protocol support are separate issues; changing the package extension will not fix an incompatible configuration.

After installation, import a subscription through the client interface and check that the core starts successfully. Whether the system proxy works also depends on the desktop environment and the app; some programs need separate proxy settings. Before enabling TUN, check virtual network interface permissions, existing routes, and other traffic-capture tools, and keep a way to restore the original network settings.

If your browser works but other apps cannot connect, first check whether those apps use the desktop proxy settings. Then decide whether to configure an app-specific proxy or use TUN. If the client fails to start, check the logs for permission, dependency, or configuration field errors. Do not confuse a client that failed to launch with an unreachable remote server. For distribution-specific requirements, follow the download page and system prompts.

Go to downloads

Browse all clients →Not sure which one to use? Start with the client selection guide.

Project V, V2Fly, and Xray

Distinguish projects, cores, and clients before deciding where to change a setting.

The ecosystem at a glance

Project V: Projects and tools
V2Fly / Xray: Core implementations and their separate development
v2rayN / v2rayNG / v2flyNG: GUI clients for end users

Compare clients and cores →

From Project V to the core ecosystem

Project V is a project ecosystem built around proxy communications, and V2Ray is one of its best-known tools. As the community developed, V2Fly continued maintaining and evolving V2Ray, while Xray emerged from related code as an independent fork with its own features and configuration support. Understanding this history helps avoid treating the three names as interchangeable labels for the same software. They share technical roots, but their current capabilities should be checked separately. A feature added in one fork cannot automatically be assumed to work in another.

In everyday conversation, “V2Ray subscription” is often used broadly to mean a set of proxy server configurations. The label does not guarantee that every client can parse everything in the subscription. It may contain different protocols, transports, and security parameters, which the client must convert into a configuration the target core understands. Importing successfully is just the first step: confirm that the selected server has all required parameters, the core starts normally, and the connection uses the expected outbound.

Clients manage settings; cores handle connections

v2rayN provides a desktop GUI for organizing subscription groups, selecting servers, managing routing, and changing proxy modes. Its actual network capabilities depend on the core and related components in use; check the options in your current release. v2rayNG is an open-source Android client using the Xray core, while v2flyNG is an Android alternative using the V2Fly core. All three clients are primarily managed through a GUI, but menu locations, import formats, and advanced options differ. Match tutorial instructions to the interface you are using.

For REALITY configurations, distinguish the protocol, transport layer, and security mechanism. REALITY is not a general-purpose acceleration option you can enable with a click on any server. Both ends of the connection need matching settings and compatible implementations. Do not change key subscription parameters based on guesswork; check the source if anything required is missing. Changing the client icon or switching interface editions will not fill in remote settings or change which protocols the server supports.

What open-source licenses mean

Open source means code can be viewed, used, modified, or distributed under the terms of its license; it does not mean every related project uses the same license. The V2Ray core from V2Fly is released under the MIT License, while the Xray core uses MPL 2.0. GUI clients, cores, and bundled components may each have separate terms. For everyday use, check the client's project information to see what it includes. Before modifying or redistributing software, review each relevant license rather than assuming the core's license applies to the entire package.

Publicly available code does not replace local access controls. Subscription URLs may be tied to an account, configurations may contain server addresses and credentials, and logs may record destinations. When sharing screenshots, keep the error type and necessary details visible, but redact sensitive information. Before enabling “Allow connections from the local network,” check the listening address, authentication, and firewall scope. This setting controls whether other devices can access your local proxy port; it is not necessary to make the current computer's connection more stable.

Update the client—and check your configuration and rules

The client application, proxy core, subscription content, and geoip and geosite rule data are separate update targets. A client update can change the interface and how configuration is generated; a core update can change supported fields; a subscription update fetches server parameters; and a rule database update affects domain and address classification. If a site does not route as expected, first check which rule matched and its position. Then decide whether the data files need updating rather than replacing every component at once.

Before updating, back up custom routing and DNS settings and note the current proxy mode. After the update, test the basic connection with your existing configuration before enabling new features one at a time. If a problem started after a change, reverting the last change is usually easier to diagnose than adjusting ports, DNS, and routing together. Some GUI clients regenerate their runtime configuration, so direct edits to generated files may be overwritten on the next launch. Save persistent changes through a customization option supported by the client.

Break connection problems into testable steps

A failed subscription update and a failed server connection are different problems. For an update failure, check that the subscription URL is complete and still valid, and find out which network path the update request uses. For a connection failure, check the selected server, protocol parameters, system clock, and core logs. Seeing a server list does not mean the system proxy is enabled, and a working browser does not mean every app uses the same proxy settings. Check in order—import, startup, traffic capture, DNS resolution, and routing—to avoid reinstalling without evidence.

Start with the system proxy for everyday use, confirm the basic connection, then add routing rules. Enable TUN only when you need to capture traffic from specific apps. Advanced topics such as DNS and FakeDNS require an understanding of the core and routing strategy; copying a single setting is not enough. The tutorial covers importing subscriptions, choosing a mode, and testing the connection. The advanced configuration manual covers filters, custom outbounds, and complex DNS setups. If you have a specific error, check the FAQ for the relevant step before deciding what to change.

Notes / Configuration

Configuration and platform guides

Explore how everyday settings work, starting with specific issues such as permissions and background activity.

Platform Guides2026-10-15

v2rayNG Per-App Proxy and Battery Optimization: Android VpnService Setup

Background disconnects and apps that bypass the proxy need separate troubleshooting. This guide explains the VpnService capture scope, per-app proxy lists, battery optimization exceptions, and the order to check autostart settings. Learn to tell the difference between an app that is not being captured and one that is routed through a different outbound.

Read the article →

Ecosystem2026-09-28

Project V, V2Fly, and Xray Explained: The V2Ray Open-Source Ecosystem and Client Lineage

Trace the history from Project V to the V2Fly community and Xray fork, then compare how v2rayN, v2rayNG, and v2flyNG fit in. Learn what the GUI and core each do, and why protocol compatibility cannot be judged by the client name alone.

Read the article →

Platform Guides2026-09-09

v2rayN macOS “Apple Could Not Verify This App Is Free of Malware” Warning: Security and Network Permissions

If macOS blocks the first launch, verify the file source before following the “Privacy & Security” prompt to allow it. This guide walks through startup permissions, network access, and proxy-related authorization separately, so you can identify the actual restriction instead of reinstalling without fixing the required permissions.

Read the article →

Browse all articles →