Starting with client installation, the guide covers subscription imports, traffic routing, and troubleshooting across common desktop and Android workflows.
Chinese documentationOpen-source codeXray · V2FlyGraphical clients
The configuration path from subscription entry to outbound verification
Client configuration is not a collection of isolated switches. A subscription supplies node details, routing determines where traffic goes, and the system proxy or TUN mode takes over application requests. Logs and connectivity tests then confirm whether each part of the path is working as expected.
subscribe / input
Importing, updating, and verifying subscription nodes
A subscription link is the entry point for retrieving node configuration. On desktop, add the URL under subscription groups and then run an update. On Android, import from the clipboard or scan a QR code from a trusted source. A completed import does not prove that the connection works: first check whether the node list appears, names display correctly, and the group matches the expected source. If the list is empty, verify that the URL is complete, the network request succeeded, and the client log shows a valid response before repeatedly changing the system proxy.
When a subscription is updated, the client reads the remote content again and may replace older nodes in the same group. Keep long-term manual configurations in a separate group so they are not mixed with subscription updates. Once the nodes appear, run a connection test to distinguish a successful subscription fetch from a reachable individual node. This order narrows the issue to input, parsing, or connection, instead of encouraging aimless changes to DNS, ports, and routing rules.
routing / match
Match order for domain, IP, and process rules
Traffic routing determines whether a request uses the proxy outbound, connects directly, or is blocked. Rules commonly inspect the domain, destination IP, port, network type, or process, and match them in the order defined by the client. When troubleshooting routing, first confirm that the client has taken over the request, then check the matched rule and final outbound. A page loading successfully alone cannot show which path the request took. As rule sets grow, priority becomes more important; narrow, clearly scoped rules should generally come before broad ones.
Domain rules work well for services with stable names, IP rules for known address ranges, and process rules for targeted desktop-app handling. After enabling a new rule set, test representative targets for direct, proxied, and blocked outcomes, and review routing records in the logs. If the result is unexpected, temporarily disable the most recently added rule and restore rules one by one. Do not change the node, DNS, and proxy mode at the same time, or it becomes difficult to identify which setting changed the path.
tun / capture
Coverage of system proxy and TUN mode
The system proxy works well for browsers and standard desktop applications that follow the operating system’s proxy settings, and it is easy to disable and restore. Some programs bypass the system proxy or open network connections directly; TUN mode can help in those cases. TUN receives a wider range of traffic through a virtual network adapter and passes it to the core for routing and outbound handling, adding considerations such as network permissions, routing tables, DNS resolution, and the local firewall. Choose the capture method based on application behavior rather than enabling every option by default.
Before switching from the system proxy to TUN, record the current local listening port and proxy status, and exit other network tools that may create virtual adapters. After enabling TUN, test the browser, target application, and domain resolution separately. If the network does not recover after the client exits, first check leftover system proxy settings, virtual adapter status, and DNS configuration. The first desktop TUN setup may require elevated permissions; mobile devices may show a system-level network connection confirmation. Platform-specific steps and rollback paths are available in the usage documentation.
debug / verify
Read status and logs by connection layer
Troubleshoot in this order: client process, local entry point, node connection, remote outbound, and domain resolution. If the client cannot start, check port conflicts and permissions. If it starts but an application cannot connect, inspect the system proxy and capture scope. If a node test times out, examine node parameters, the network environment, and transport settings. Only shift focus to DNS when domain access fails while direct IP access works. Mapping symptoms to layers is more effective than repeatedly changing nodes or reinstalling the client.
Read timestamps, severity, and error locations in the context of the action that triggered them. After running a subscription update, starting a connection, or opening the target application, check the newly added log entries immediately to reduce interference from history. Port conflicts usually point to local listening; connection timeouts often occur at the node or transport layer; resolution failures call for checking the DNS request path. After a fix, repeat the original trigger and confirm that the error no longer appears, then verify that the system proxy has returned to the expected state.
platform entry
Download entry points for Windows, macOS, Android, and Linux
Use v2rayN across desktop platforms. On Android, choose between v2rayNG and v2flyNG according to your core requirements. Platform links jump to the matching tab on the download page, where package types, system requirements, and architecture options are explained together.
desktop / windows
Windows · v2rayN
Windows users can choose between the newer desktop interface and the classic WPF interface. After installation, import a subscription and select a node before configuring the system proxy. If startup reports that a local port is already in use, identify the process holding it or change the listening port, then update the proxy settings accordingly. The download page also explains the differences between the two interfaces to help you choose for your current system.
Before downloading for macOS, confirm the processor architecture: Apple Silicon and Intel use different installers. The first launch may also require system security approval and network access permission. Grant access in System Settings, then return to the client and import the subscription. After connecting, check the menu bar status and system proxy before testing applications, so permission issues are not mistaken for node failures.
The main Android option is v2rayNG with the Xray core; choose v2flyNG when you prefer the V2Fly core. Most newer devices use the arm64 architecture. If you are unsure, check the universal installer on the download page. After importing a subscription, select a node and start the system network connection. Then check connection status, per-app settings, and battery background restrictions to prevent the system from stopping the client after the screen locks.
For Linux desktops, choose a deb or rpm package for your distribution and confirm whether the system uses x64 or arm64. After installation, manage subscriptions, nodes, and routing rules through the graphical interface. If the system proxy does not affect the target application, check the desktop environment’s proxy settings and whether the application maintains its own network configuration. For broader traffic capture, evaluate TUN permissions and virtual adapter status.
Understanding the roles of clients, cores, and protocols helps identify which layer contains a configuration issue and prevents graphical interface names, subscription formats, and transport protocols from being conflated.
project / lineage
From the V2Ray project to the core family
V2Ray grew from the Project V ecosystem, whose central idea was to separate inbound, routing, outbound, and underlying transport into composable configuration modules. As community maintenance evolved, V2Fly continued the v2ray-core lineage, while Xray developed a separate core branch around similar configuration concepts. Both can handle multiple proxy protocols and transport methods, but their fields, feature support, and defaults may differ. Before importing a configuration, confirm which core the client uses and whether the subscription contains parameters that core can recognize.
Graphical clients sit above the core and handle subscription management, node selection, the system proxy, log viewing, and update settings. v2rayN targets desktop platforms and can call the relevant core through the options provided by the software. v2rayNG primarily uses the Xray core, while v2flyNG follows the V2Fly core line. A client name is not a protocol name, and choosing a client does not mean every node uses the same protocol. The actual path depends on the node configuration, transport layer, TLS settings, routing rules, and the client’s capture method.
license
Open-source licensing and code boundaries
The V2Fly core, Xray core, and the three graphical clients maintain their own code and license files. Core projects and clients may use different open-source licenses, and release packages may include their own dependencies. For licensing details, rely on the notices included with the corresponding software release rather than treating the entire ecosystem as one project. Open code and configuration formats make it easier for the community to review implementations, discuss compatibility, and fix issues over time.
maintenance
Update the client and core independently
Graphical interfaces and network cores follow different release cycles. Client updates may change subscription management, interaction, or system integration, while core updates focus more on protocol implementation, transport capabilities, routing, and network behavior. When an issue appears after an upgrade, first determine whether the change came from the client or the core, then consult the logs and configuration migration notes. The download page provides current installation entry points; the homepage does not display release information that may change quickly.
configuration
Protocol, transport, and routing layers
VMess, VLESS, and Trojan describe protocol-layer configuration. WebSocket and gRPC are transport methods. TLS and REALITY cover connection authentication and secure transport. Routing rules determine which outbound handles a request. Check each layer in order: do not change protocol parameters merely because domain resolution failed, and do not repeatedly adjust remote nodes when the application has not entered the local proxy.
v2rayN
Desktop graphical clients
For Windows, macOS, and Linux, manage subscriptions, nodes, routing, the system proxy, and TUN settings in one place. Suitable for users who need to inspect logs, maintain multiple subscription groups, and fine-tune traffic capture on a desktop.
v2rayNG
Android · Xray line
Designed around mobile workflows, with subscription import, node selection, per-app proxying, routing, and system network connection management. When connections drop in the background, also check the device’s battery policy and background-running permissions.
v2flyNG
Android · V2Fly line
For mobile configurations that require the V2Fly core, providing an alternative core choice on Android. Before importing, verify the subscription parameters against the core’s supported range so core differences are not mistaken for an invalid subscription URL.
latest notes
Advanced configuration and troubleshooting articles
These articles focus on specific symptoms and configuration steps, explaining the underlying concepts, procedures, result checks, and rollback methods. Complete the basic installation and subscription import first, then choose the topic that matches the issue at hand.
Advanced
How to enable TUN mode: virtual network adapter traffic capture and configuration steps
Learn the fundamental difference between TUN mode and the system proxy, how virtual network adapters, routing tables, DNS, and application traffic interact, and how to enable TUN in v2rayN and v2rayNG. The article also covers checks for insufficient permissions, an unrecovered network connection, and conflicts with other virtual adapters.
What to do when a port is in use: identify the process and change V2Ray’s local listening port
When the client reports a port conflict at startup, first identify the listening port and the process using it, then decide whether to stop the old process or change the configuration. The article explains diagnostic approaches for common desktop systems and why system and application proxy settings must be updated after changing the port.
DNS leak detection and repair: keep domain resolution and traffic on the same path
Starting with the domain-resolution path, this article explains why resolution requests can still use another network interface even after the client connects. It covers detection methods, DNS settings to check in v2rayN and v2rayNG, and before-and-after request paths for confirming that the fix works.