Desktop and Android client guides

V2Ray & v2rayN Guide

A focused reference for client installation, subscription imports, and split routing. Menu names match the client interface, so the basic setup can be completed step by step.

Free forever Open-source code Xray and V2Fly ecosystem Setup documentation

Client Settings Panel

Subscriptions, Routing, and System Control

Choose a use case first, then review the relevant settings. Examples use familiar client menu names and rule syntax.

Subscription Group List

Keep sources, filters, and update actions in one group

On desktop, save the complete subscription URL under “Subscription Groups” before selecting “Update Current Subscription.” Create separate groups for home, work, or testing to keep unrelated sources out of one server list. If the list is empty after an update, first check the group filter and confirm the URL is complete instead of repeatedly toggling the system proxy.

Path: Subscription Groups → Add Subscription → Update Current Subscription

Choose by Platform

V2Ray Client Download

Use v2rayN on desktop. On Android, choose between v2rayNG and v2flyNG according to your core requirements. The homepage helps identify the right platform; package types and system requirements are listed on the download page.

Windows

Choose the v2rayN desktop edition or the classic WPF edition. The desktop edition uses a cross-platform interface, while the WPF edition keeps the familiar Windows workflow. Both manage subscriptions, routing, and the system proxy.

Go to Downloads

macOS

v2rayN offers installation packages for different chip architectures. Check the chip type in “About This Mac” or the system’s device information before downloading, then follow the system prompts for app and network permissions on first launch.

Go to Downloads

Android

v2rayNG uses the Xray core, while v2flyNG uses the V2Fly core. Most newer devices can start with the arm64 build; if you are unsure of the device architecture, use the universal package.

Go to Downloads

Linux

v2rayN provides deb and rpm desktop packages in both x64 and arm64 variants. Choose the file that matches your distribution’s package format and processor architecture.

Go to Downloads

Quick Start

Three Steps from Installation to Split Routing

Start with the smallest working configuration, then add routing, DNS, and TUN settings gradually. Changing too many options at once makes troubleshooting harder.

  1. 1

    Install the Client and Import a Subscription

    Open the download page for your platform. Use v2rayN on Windows, macOS, and Linux; on Android, choose v2rayNG or v2flyNG. After installation, open “Subscription Groups,” create a group, paste the complete subscription URL, and update it. A single share link can be imported from the clipboard, but unlike a subscription, it will not update as a group.

    After updating, check whether the server list contains entries. If it is empty, check for a truncated URL, overly strict group filters, and whether the update applied to the current group. There is no need to change the system proxy yet, because subscription parsing happens before connection.

  2. 2

    Select a Configuration and Enable System Control

    Select a configuration in the server list and make it active. On desktop, enable “System Proxy” so browsers and apps that read system proxy settings use it. On Android, start the connection and approve local VPN access when prompted. Then visit a familiar page to confirm basic connectivity.

    Consider TUN mode only when the target app ignores the system proxy or broader traffic control is necessary. After enabling it, check that local development services, LAN devices, and DNS remain reachable as expected. Do not enable complex routing and FakeDNS before basic connectivity is confirmed.

  3. 3

    Add Routing Rules and Check Logs

    Once the basic connection is stable, configure split routing. Rules match in order, so place specific domains or private-address conditions before broader rules. Common entries include geosite:cn, geoip:private, and geosite:geolocation-!cn, with direct or proxy as the corresponding outbound.

    Save and reload the configuration, then use logs to confirm rule matches, DNS behavior, and outbound selection. If something breaks, return to the previous step and undo recent changes one at a time. Do not replace the subscription, protocol, DNS, and system-control mode simultaneously; isolating changes identifies the affected layer.

Open-Source Ecosystem

How Project V, V2Fly, and Xray Relate

Understanding the roles of clients, cores, and protocols helps identify where a configuration problem occurs. Graphical clients import, edit, start, and stop configurations; cores parse protocols, establish connections, and apply routing; subscriptions carry configuration data in bulk.

Project V and V2Fly

Project V established an open-source ecosystem centered on V2Ray configuration, protocol implementations, and routing. V2Fly continues to maintain related core components and familiar inbound, outbound, routing, DNS, and transport structures. v2flyNG uses the V2Fly core and suits Android users who want to stay within that core family.

In everyday use, “V2Ray” may refer to the ecosystem, configuration style, or a class of clients, but these concepts are not identical. When an error appears, first determine whether it comes from the graphical interface, subscription parsing, or core logs. Separating these layers prevents interface issues from being mistaken for protocol problems.

The Xray Core Family

Xray extends a related configuration ecosystem with additional protocol and transport capabilities. v2rayN can use the appropriate core components for specific features and configurations, while v2rayNG uses Xray as its primary Android execution layer. Whether VLESS, REALITY, or gRPC works depends not only on the client name, but also on core support, server settings, and complete parameter alignment.

After importing a link, the client converts its fields into an internal configuration, but that does not make every combination valid. Server name, flow control, fingerprint, public key, short ID, path, and host fields each have a defined purpose. For handshake errors, check the protocol and transport layer field by field instead of repeatedly switching between configurations.

Open-Source Features of the Three Clients

v2rayN is a desktop graphical client for Windows, macOS, and Linux, with management views for server lists, subscription groups, routing, system proxy, TUN, and logs. v2rayNG and v2flyNG target Android and offer similar workflows, but use different core families. All three are maintained by their communities, so release schedules and platform coverage do not need to match exactly.

Open-source licensing lets the community review code, discuss implementation, and improve compatibility over time. For everyday users, the practical benefit is that settings, configuration structures, and troubleshooting discussions can be understood publicly. Choose a client based on the operating system, core requirements, protocol fields, and workflow—not just its appearance.

Update Mechanisms and Configuration Compatibility

Client updates, core updates, and subscription updates are three different actions. Client updates change the interface and integrated features; core updates affect protocol implementation and runtime behavior; subscription updates only synchronize configuration content. When troubleshooting an update, identify which layer changed and keep the current working configuration for comparison.

Existing configurations can usually be imported into newer versions, but new fields may need to be saved again or added manually. Users with multiple subscriptions should give each group a clear name to avoid updating the wrong source. Record local routing and DNS settings separately, since they may not be included in a remote subscription.

Selected FAQs

Installation, Subscriptions, and Connection Checks

Use these questions to quickly identify where to start troubleshooting. Full causes, interface paths, and fixes are covered in the FAQ and advanced configuration guide.

The Server List Is Empty After a Subscription Update

First confirm that the subscription URL is complete, then check the filter keywords for the current group. Filters may hide every configuration that parsed successfully. If the URL requires the existing connection, also verify the network path used during the update.

View subscription troubleshooting →

Some Apps Do Not Change After Enabling the System Proxy

Some apps ignore the system proxy or use their own network settings. Check the app’s proxy options first, then consider TUN mode if needed. Do not expand the control scope before the basic configuration is verified.

View connection steps →

Latency Test Results Do Not Match Real-World Experience

A latency test reflects connection time under one specific test method and cannot represent transport stability on its own. Also consider region, route fluctuations, traffic multipliers, protocol overhead, and the actual destination.

Read the node selection guide →

How Should geosite and geoip Be Ordered?

Rules match from top to bottom, so specific conditions should come before broad ones. Use geosite for domain categories and geoip for destination addresses; private addresses should generally use direct.

View routing examples →
V2Ray Client Download