Client downloads / configuration reference

V2Ray Release Hub

v2rayN downloads and setup guides

Download v2rayN View setup guide

From importing VLESS nodes to routing, find client downloads for four platforms and a guide to config.json fields.

Protocols
VMessVLESSTrojanShadowsocksREALITY
Platforms
Windows Android macOS Linux

CLIENT / PLATFORM

Choose a client by platform

Browse all clients →

Start with v2rayN for desktop or v2rayNG for Android. Check your operating system and processor architecture before choosing an installer. The same subscription can work across clients, but interface options, local ports, and routing presets may differ. The download page explains installer options and package types; this home page does not list specific versions.

Windows

v2rayN / Desktop · WPF

Manage subscription groups, choose nodes, and control the system proxy from your desktop. The download page offers a modern cross-platform edition and the classic WPF edition. Check system compatibility first, then choose the interface you prefer; there is no need to install both on the same computer.

After the first launch, make sure the core runs and its local listening ports are not in use before importing nodes. Before updating, keep your subscription groups and custom routing rules. To migrate settings, use the client's supported export options instead of overwriting files in the runtime directory.

Go to downloads Windows client →

macOS

v2rayN / Apple Silicon · Intel

Use v2rayN to manage desktop subscriptions and routing on macOS, too. Check your chip under About This Mac: choose arm64 for Apple Silicon or x64 for Intel. The processor architecture determines which installer you need, so don't rely on the computer's appearance or purchase date.

After installation, follow macOS prompts about launching the app and granting network access. The system proxy only affects apps that honor it; terminal tools and apps with their own proxy settings may need separate configuration. When troubleshooting, first check which proxy route the affected app actually uses.

Go to downloads macOS client →

Android

v2rayNG / v2flyNG

Start with v2rayNG, which uses the Xray core. If you need compatibility with V2Fly configurations, consider v2flyNG. Most newer devices use arm64; if you are unsure about your architecture, check the universal package guidance. The clients use different cores, so similarly named options are not necessarily interchangeable.

On first connection, approve the system VPN request. If another VPN is already connected, check for a conflict. Background disconnections can also result from battery optimization or background activity limits. Allow background activity, then check the logs for node or DNS issues.

Go to downloads Android client →

Linux

v2rayN / deb · rpm

Choose a deb or rpm package to match your distribution, then check whether your system uses x64 or arm64. Debian-based distributions and those using RPM package management have different download options; package format does not indicate feature level. Your desktop environment, system dependencies, and network permissions can also affect installation and startup.

The graphical client manages nodes and settings; the core handles network traffic. Whether the system proxy works depends on your desktop environment and app support. If a browser connects but command-line tools do not, check each tool's proxy settings before switching nodes or rewriting the entire configuration.

Go to downloads Linux client →

CONFIG / FIELD INDEX

Client features and configuration fields

Browse the configuration reference →

The graphical client organizes nodes and settings; the core reads the configuration and handles connections. Here's how their roles differ in practice. The code snippets are partial examples to help locate fields, not complete configurations that can connect as-is. Check syntax against the core you use.

Protocols, transports, and security

VMess, VLESS, Trojan, and Shadowsocks are outbound protocols; separate fields control the transport and security layers. After importing a node, check the server address, port, transport, and TLS settings together. REALITY is a security mechanism, not a standalone node protocol. Whether v2rayN or v2rayNG supports a particular combination depends on the core in use. Rather than filtering by protocol name alone, check the full set of parameters provided by the server, then review the handshake logs.

Read about outbound fields →
{
  "outbounds": [
    {
      "tag": "direct",
      "protocol": "freedom",
      "settings": {}
    }
  ]
}

START / THREE STEPS

From import to connection checks

Read the full guide →

Know the difference between three things

Client, node, subscription

A client is a local management interface, a node is a set of remote connection parameters, and a subscription is a URL for retrieving a list of nodes. Installing a client does not give you a working node; the software does not include a generic server account. Knowing the difference helps pinpoint whether a problem lies with installation, import, or connection.

Share links and subscription URLs may contain access credentials. Don't post a full URL in a public screenshot or send it to an unfamiliar conversion service for testing. When reporting an issue, include the error type, core name, and relevant fields, but redact identity parameters in URLs.

If you have an old client configuration, note the node, proxy mode, and custom rules in use. For your first migration, get a minimal connection working, then restore additional settings one at a time. This helps prevent old configuration issues from carrying over to the new setup.

Choose a client →

  1. Import a subscription or share link

    In v2rayN, open subscription group settings, add a subscription URL you control, save it, and update the subscription. To import a single node, use clipboard import. In v2rayNG, you can add nodes through a subscription group or a share link. Menu labels may change; choose based on what you're importing: use the subscription option for a remote list of nodes and the node import option for a single protocol link.

    After updating, make sure nodes appear in the list and check that their names, addresses, and protocols look right. A successful import only means the client could read the data; it does not mean the server is online. If the list is empty, check whether the subscription URL has expired, requires authorization, or cannot be reached from your current network.

  2. Choose a node and proxy mode

    Select a node, then set the system proxy and routing mode for your task. The system proxy determines whether an app sends traffic to the client; routing determines where the client sends that traffic. One cannot replace the other. On desktop, test first with a browser that honors the system proxy. On Android, make sure you have approved the system VPN request.

    For your first connection, stick with the client's default routing settings. TUN creates a virtual network interface and requires extra permissions; it isn't needed for every connection. Once the standard proxy path works, decide whether to use TUN based on whether your target apps support proxies. Avoid changing several network layers at once.

  3. Test access and check the logs

    Open a page that should use the selected route, then check the client logs. Latency tests are useful for reference but don't replace testing in a real app. A node's test result does not guarantee that DNS, TLS, or access to the target website is working. Start with one page to keep the logs readable; avoid sending many concurrent requests.

    For timeouts, check each step in order: local inbound, system proxy, routing match, then remote outbound. If a connection is refused, check the listening and destination ports. For handshake errors, check the system clock, server name, and security parameters. Compare results after each change; replacing multiple settings at once makes the cause harder to find.

PROJECT V / CORE / CLIENT

Open-source ecosystem and core differences

Compare clients →

The interface manages settings; the core handles connections

The Project V ecosystem

V2Ray is a network proxy tool in the Project V ecosystem. A useful way to understand its configuration is to split it into inbound, routing, and outbound sections: inbound accepts app requests, routing checks matching conditions, and outbound makes the connection. DNS, policy, and logs cover resolution, connection behavior, and runtime records. This is also a practical order for reading config.json.

V2Fly

Continues V2Ray's community-led development, maintaining the core and related configuration features.

Xray

An alternative core originating in the V2Ray ecosystem, with its own protocols and security mechanisms.

A similar configuration structure does not guarantee identical syntax. If a field is not recognized, check the core type and its supported features before assuming the node is broken. Protocol extensions, transport options, and security-layer combinations in particular depend on the capabilities of the core in use.

What each of the three graphical clients does

v2rayN is for desktop use, with centralized management for subscriptions, nodes, routing, and optional cores. v2rayNG is for Android and uses the Xray core; v2flyNG is an Android option based on the V2Fly core. All three are open-source projects, but client names are not protocol names, and a client update does not mean all cores have identical capabilities.

The graphical interface turns common tasks into options, but the core still needs a generated configuration to run. A single toggle in the interface may affect several JSON fields; conversely, the client may not provide a visual control for every low-level parameter. Before customizing a configuration, learn how the client saves, generates, and overwrites runtime files to avoid losing edits when the interface regenerates them.

Open-source licenses and community maintenance

Open source means source code is available under terms that allow use, study, and modification; it does not mean every component uses the same license. The V2Fly and Xray core code is primarily licensed under MPL-2.0. Check the license for each client, dependency, and bundled component separately. When modifying or redistributing software, follow the relevant attribution, source-availability, and other requirements; “free” alone does not define the terms of use.

Community projects typically develop interface improvements, configuration compatibility, and core updates separately. When reading release notes, identify which layer a change affects: an interface update may only move controls, while a core change can affect protocol parameters, connection behavior, or rule support. This site organizes client downloads and configuration guides; it does not replace project license notices or provide node services.

Keep a rollback option before and after updates

Before updating, save your subscription groups, custom nodes, and custom rules. Afterward, check the startup logs and test your usual nodes and apps. If only one type of connection is affected, temporarily restore the related routing or DNS settings and compare one change at a time instead of clearing everything. Avoid leaving highly verbose logging on longer than necessary, and remember that logs may include visited domain names.

Learn configuration in the same order: get a basic connection working, understand outbound tags and rule matching, then adjust DNS and policies. Knowing which stage each field affects makes it easier to tell whether a change actually fixed the issue. For field types and examples, see the configuration reference.

NOTES / LATEST

Configuration and troubleshooting articles

Browse all articles →

Once your basic connection works, find an article for the issue at hand. Protocol guides explain how configuration fields work, node selection guides help interpret test results, and troubleshooting checklists narrow down possible causes. Keep a working configuration and test one change at a time.