Client and configuration documentation
A focused guide to v2rayN and v2rayNG clients, subscription imports, and Windows / macOS / Android / Linux setup, covering installation, connections, routing, and DNS.
Key client settings
The core workflow in a graphical client goes beyond adding a subscription. Group organization, proxy entry points, routing rules, and DNS resolution paths together determine connection stability, which apps use the proxy, and whether local-network and local services remain accessible as expected. The four key stages below follow the practical setup order.
Subscription groups are useful when maintaining several configuration sources at once. Each group can have its own update interval, enabled status, and server filters, so updates from different sources remain separate. For a first setup, create one primary group, import the subscription URL, run a manual update, and confirm that server entries appear. As sources grow, split groups by purpose or provider instead of relying on name prefixes to find entries.
When the server list becomes long, use include or exclude keywords to narrow what is shown, then run a real connection test for the current group. Filtering only changes how the list is organized; it does not alter the original subscription configuration. Clear the filter to restore the full list.
Include keyword
The system proxy works well for browsers and desktop apps that follow the operating system's proxy settings. It is straightforward to enable and useful for troubleshooting an initial connection. TUN mode uses a virtual network interface to handle more types of application traffic, including software that ignores system proxy settings, but it usually requires extra permissions and can be affected by other network tools, virtual adapters, or firewall rules.
Start with the system proxy for subscription imports, server selection, and web access checks. Once the basic connection works, switch to TUN only if an application requires it. If local services become unreachable or the network drops, disable TUN first, then check permissions, routing, and DNS instead of changing several settings at once.
GENERAL
Traffic routing uses domains, IPs, ports, or network types to choose an egress path. A common approach is to keep LAN addresses and local services on a direct connection, send proxy-bound destinations through the active server, and block destinations that should not be accessed. Rules are usually matched from top to bottom, so narrow exceptions should come before broad rules to prevent an earlier, wider match.
When adjusting routing, change one rule group at a time and verify the result with a specific website or app. If a rule relies on a domain but the connection only exposes an IP, also check DNS resolution and domain sniffing. Add short notes to complex rules so their purpose remains clear later.
private
Direct
domain:example
Proxy
protocol:bittorrent
Block
DNS settings determine which address a domain resolves to and can indirectly affect whether routing rules identify the destination correctly. For basic use, keep the client's recommended settings until subscriptions and the system proxy work normally. If direct and proxy-bound domains need different treatment, configure separate resolvers and align each lookup path with its final connection route to reduce conflicts between resolution results and actual routing.
If a webpage opens but an app cannot connect, the same domain resolves inconsistently, or switching modes causes temporary issues, clear the system DNS cache and restart the client first. Avoid making major changes to DNS, TUN, and routing rules at the same time; otherwise it becomes difficult to identify the affected layer.
DNS
Choose by operating system
v2rayN is the main desktop choice, while Android users can choose between v2rayNG and v2flyNG based on core requirements. On the download page, select a file by processor architecture and installation format.
v2rayN is the recommended choice. The desktop edition offers a cross-platform interface, while the classic WPF edition suits users who prefer the traditional Windows workflow. After installation, start with a subscription group and enable the system proxy to verify the connection.
Use the macOS build of v2rayN. Before downloading, check System Information to identify an Apple Silicon or Intel processor and choose the matching installer. Complete any required permissions when prompted on first launch.
Choose v2rayNG with the Xray core by default; use v2flyNG when the V2Fly core is required. Most recent devices work well with an arm64 build. If the processor architecture is unknown, choose the universal build.
Use the Linux build of v2rayN and choose deb or rpm according to your distribution's package system. You also need to distinguish between x64 and arm64. After installation, launch it from the desktop and configure the system proxy or TUN.
Quick start
For a first setup, follow a fixed order: import the subscription, choose a server and run a real connection test, then enable the system proxy and check the egress address. Each step produces a clear result, making it easier to determine whether an issue lies with the subscription, server, or local proxy settings.
View the complete guide →Open Subscription Groups in the client, create a group, paste the subscription URL provided by your service provider, save it, and run an update. Configuration entries should appear afterward. If the list is empty, check that the group is enabled, that no spaces were added around the URL, and that the current network can reach the subscription source. Before creating more groups, check the log to confirm the update request result.
Select an entry from the current subscription group, run a real connection test, or set it as the active server. The result reflects the time required to establish an actual connection and is more representative of everyday use than a basic network probe. If several entries fail, first check whether the subscription has expired, the system clock is accurate, and the core loaded correctly instead of repeatedly switching proxy modes.
For the first connection, enable the system proxy, open a familiar webpage in a browser, and check whether the egress address changes as expected. If the browser works but another app does not, that app likely ignores system proxy settings; consider TUN or the app's own proxy options. After verification, continue with routing rules, startup behavior, and the subscription update interval.
Open-source ecosystem overview
Understanding the relationship between clients and cores helps identify whether an update affects the interface layer, core processing, or protocol implementation. Graphical clients handle subscriptions, lists, rules, and system integration; cores handle protocols, routing, and network connections. Their responsibilities differ, and their release schedules may not align.
Project V is an open-source ecosystem built around proxy protocols, routing capabilities, and composable networking tools. Early V2Ray established foundational concepts such as configuration structure, multiple inbounds and outbounds, and route matching. Community maintenance later evolved along different branches. Modern clients do not reimplement every feature; they call a core and present complex configuration through a graphical interface suited to desktop or mobile use.
When you see “V2Ray client,” distinguish three layers: the graphical client operated by the user, the core that executes connections and rules, and the protocol parameters described by a subscription or manual configuration. Troubleshoot by layer: missing imported entries indicate subscription management, a failed core startup indicates a core issue, and an unexpected egress for a specific domain usually points to routing or DNS.
V2Fly continues the maintenance direction of the V2Ray community branch, preserving a composable configuration system while updating protocol, transport, and routing capabilities. Xray is another core family in the ecosystem, developing its own protocol implementations and feature combinations while remaining compatible with common configuration concepts. Neither is a graphical client or the same thing as an app interface on a particular operating system.
When choosing a core, focus on the protocols required by the subscription, client support, and compatibility with existing configurations. Most users do not need to switch cores manually often. If a provider explicitly requires a capability or the log says the current core cannot recognize a configuration field, adjust it according to the documentation. After a core update changes behavior, check the client log and migration notices before rebuilding every subscription and route.
v2rayN is a widely used desktop graphical client for Windows, macOS, and Linux. It provides access to subscription groups, server lists, system proxy, TUN, routing, DNS, and core management. Permission flows and system integration details may differ across desktop systems, but the main configuration logic remains consistent, making it suitable for users who want the same workflow across desktop platforms.
v2rayNG targets Android and is typically used with the Xray core, organizing configuration lists, subscription updates, routing, and connection controls in its interface. v2flyNG also targets Android but uses the V2Fly core, making it an alternative when a specific core is required. Both mobile clients can import subscriptions or maintain separate configurations; before migrating, confirm the protocols and fields supported by the subscription.
Clients and cores are maintained as open-source projects, with each community handling feature discussions, bug fixes, and releases. Open-source licenses define the boundaries for using and redistributing code while allowing the implementation to be reviewed. Specific licenses vary by project; when using, modifying, or redistributing code, follow the license included with that project.
Client updates usually cover the interface, system integration, subscription handling, and how the core is invoked. Core updates focus more on protocol implementation, transport, routing, DNS, and runtime efficiency. The two types of updates do not always arrive together. Read the release notes first, check for configuration migrations or permission changes, and then schedule the update. When something goes wrong, keeping the log and current configuration is more useful than simply reporting “unable to connect.”
Technical notes
These three articles cover the main interface, core ecosystem relationships, and multi-subscription management, making them useful follow-up reading after your first connection.
Break down the server list columns, subscription group labels, log window, and settings entry points to establish a clear interface workflow.
Read the full article →Explore the origins of Project V, the V2Fly community branch, and the Xray core family, along with the platforms and cores associated with v2rayN, v2rayNG, and v2flyNG.
Read the full article →Use subscription groups to isolate sources, assign update intervals and keyword filters, then test and organize server lists by group.
Read the full article →Featured FAQs
Most first-use issues can be checked in this order: installation file, subscription update, server connection, system proxy, then routing and DNS. Avoid changing multiple layers in one pass; otherwise it is difficult to tell which adjustment made a difference.
For Windows, macOS, and Linux, start with v2rayN. It brings subscription groups, server lists, system proxy, TUN, routing, and DNS into one desktop interface. Confirm the operating system and processor architecture before downloading. After installation, verify the basic connection with the system proxy, then decide whether TUN is needed for specific apps.
First confirm that the subscription group is enabled and run a manual update. Then check the log for messages such as an unreachable URL, unrecognized content format, or failed network request. Also check for spaces around the subscription URL. If the update succeeds but the filtered list is empty, clear the group filter and view the original entries again.
Not for initial setup. Use the system proxy first to verify your browser and common desktop apps, and confirm that the subscription, server, and core work normally. Test TUN separately only when an app that ignores the system proxy needs to be handled. If the network fails during the switch, restore the previous mode, then check permissions, the virtual adapter, routing, and DNS one by one.
A successful test only shows that the client can establish a connection with the active server; it does not mean every app will automatically use the system proxy. Check whether the app follows system proxy settings, then inspect its own proxy configuration, any special network interface, and whether routing rules mark the destination as direct or blocked. If the issue occurs only with domain access, also check the DNS resolution path.