Open-source clients and configuration guides

V2Ray Tutorial Hub Client downloads and setup

Start with choosing a client and importing a subscription, then follow a connection's path to understand what routing and DNS each do.

Xray V2Fly VMess
01Platform directory

V2Ray client downloads

Check your operating system first, then confirm the CPU architecture and package format. A client may offer several packages; these differences do not indicate differences in available nodes.

Windows

For a first install, start with the v2rayN desktop client. If you're already familiar with its classic interface, you can choose the WPF version. These options mainly differ in their UI implementation, so menus may have different names or locations. When following a guide, identify your interface first, then find the corresponding controls for subscriptions, routing, and the system proxy.

When migrating from an older version, keep your existing configuration and subscription details. Then use the new client to test a node that worked before. If something goes wrong, this makes it easier to tell whether the cause is a changed interface, an import issue, or a connection problem.

Go to downloads →

macOS

Check the chip or processor in system information: choose arm64 for Apple Silicon and x64 for Intel. Don't rely on the computer's appearance, product line, or purchase date; the same product line may include models with different architectures.

A successful launch only confirms that installation worked. For your first connection, check separately whether the subscription list refreshes, a node is selected, and the app you're testing uses the current system proxy settings.

Go to downloads →

Android

v2rayNG uses the Xray core; choose v2flyNG if you need the V2Fly core. Confirm that your system supports arm64, then select the matching package. If you're unsure, check the universal build notes on the download page. First choose a client that supports your configuration, then compare package size and format.

When you connect for the first time, the system may ask for permission to establish a VPN connection. Grant permission, then open a test app to check whether its traffic goes through the client. If another VPN service is already running on the device, check whether it's using the system's VPN connection.

Go to downloads →

Linux

For desktop Linux, use v2rayN. Debian- and Ubuntu-based distributions generally use deb packages; Fedora-based distributions use rpm. You also need to check the architecture—don't confuse the distribution name with the processor type. If installation fails, start with the package manager's error message and identify whether the issue involves architecture, dependencies, or permissions.

Even after installation succeeds, verify that each app can connect through the client. System proxy support varies across desktop environments, and some apps use their own network settings. If your browser works but another app doesn't, check that app's proxy settings first.

Go to downloads →
Browse all clients →
02Configuration index

Routing, DNS, and subscriptions

The client first obtains node configuration. Once app traffic enters the core, the core resolves the destination and selects an outbound route according to the rules. When troubleshooting, follow this path to find the first point where something goes wrong.

Seeing a node list means the client has obtained at least one configuration. Connecting to a node means it works under the current conditions. For a target app to connect, its traffic must also enter the client and match the expected rule. These outcomes are not interchangeable.

For an initial setup, use one node and one app to create a repeatable test. Record the connection mode, destination, and result before adding routing rules or changing DNS. Keep this record so you can tell whether a later issue came from a new setting or a change in the network environment.

Routing rules are useful when different destinations on the same device need to use different outbound routes. The system proxy determines which apps hand their requests to the client; routing determines where traffic already inside the core goes. Before editing rules, spell out the match conditions and target outbound, then place narrower exceptions before any general rules that would override them. Test one destination that should match and another that shouldn't, and check the available connection logs to see which outbound was actually used. If a rule matches but the result is wrong, check the rule order first, then the node.

Core
Xray / V2Fly
Platform
Desktop / mobile
Use case
Choose an outbound route by destination
Read the guide →
03Open-source ecosystem

Project V, V2Fly, and Xray

Knowing which names refer to projects, cores, or graphical clients explains why a guide may not apply word for word to every app—and helps narrow down troubleshooting.

Client layer
Subscriptions, node lists, configuration management
Core layer
Inbound, routing, outbound
System layer
App integration, network permissions

Project V's inbound and outbound model

Project V is a family of projects for proxy tools, with V2Ray as the core component that handles connections. The V2Fly community later continued V2Ray development, while Xray split from this codebase and evolved independently. They share several basic concepts: inbound receives traffic, routing determines where it goes, and outbound hands the connection to the next hop or rejects it according to the configuration. The four outbound names shown above are illustrative labels; actual names and behavior depend on the configuration.

For example, a browser request reaches the relevant inbound only when the browser uses the local proxy settings. The core then matches rules using the destination information available to it. If the browser bypasses the proxy, the core won't route its traffic even if it's running. Understanding this boundary is more useful than memorizing where a button was in a particular version: settings can change, but traffic still has to enter the core first.

Core branches and configuration compatibility

V2Fly and Xray maintain their own protocol implementations and configuration features. Their documentation may include fields such as inbound and outbound, but fields with the same name aren't necessarily interchangeable in every option. VMess and VLESS describe parts of a protocol; a connection also depends on the transport, security settings, and how both ends are implemented. The server configuration determines what the client needs to support—don't infer that from a region or route name in the node description.

When migrating, keep the old setup and import the same known-good configuration into the new environment on its own. If the UI recognizes the node but the core won't start, check the startup error first. If the core starts but that node won't connect, check the node parameters and network reachability. Following this order helps distinguish mismatched transport settings from an expired subscription and avoids changing all your routing rules up front.

Open-source status of v2rayN, v2rayNG, and v2flyNG

All three clients make their source code public. v2rayN is a desktop client with tools for managing subscriptions, nodes, and routing settings. v2rayNG uses the Xray core, while v2flyNG offers a mobile option based on the V2Fly core. Clients and cores are separate project layers: how subscriptions are displayed, where menus appear, or how system permissions are requested doesn't tell you whether two cores belong to the same branch.

Open-source licenses govern how code can be used, modified, and redistributed; they don't tell you whether to trust a third-party subscription service. Using a client for free and paying for a network service are separate matters. Don't post an entire configuration file publicly if it contains subscription URLs or node credentials. When reporting an issue, you usually only need to include the operating system, client and core names, the stage where the failure occurs, and an error summary with sensitive fields removed.

Client updates, core updates, and subscription refreshes

A client update may change the interface or how it integrates with the system. A core update may affect support for new features or how configurations are parsed. A subscription refresh retrieves the node list again. Installers sometimes bundle a core, so one upgrade can affect both the client and core layers. Refreshing a subscription, however, doesn't update the app or automatically fix local routing errors. When troubleshooting after an update, first find out exactly what changed.

After saving your old settings, compare before and after using the same network, node, and test destination. First check that the app launches, then that the node still works, and finally whether the existing rules match as expected. If only the routing result changed, also check whether domain or IP data was updated as part of the upgrade. Making one change at a time gives you a clear rollback point and makes it easier to provide maintainers with a useful reproduction.

Testing connections and isolating issues

Start by following the subscription import guide to get a working setup before trying more complex rules. If the list doesn't update, check the subscription source and retrieval process. If the list is current but every node fails, check your network, connection mode, and whether the core started. If only certain apps fail, check whether they use the system proxy or their own DNS settings, and which rule matches their destinations.

Don't rely on a single latency result to compare connection quality. Short web requests highlight response time, while file transfers better reflect sustained throughput; different factors affect each. Repeat comparisons on the same network and with the same test destination, noting any network, node, or configuration changes. If requests remain unstable after reverting settings, check the node and route again rather than adding more local rules.

04Featured guides

Deployment, choosing nodes, and routing

These three guides cover everything from a single-device connection to a LAN deployment, including deployment scope, node selection, and rule priority. Pick the one that matches your needs.

/ Deployment

Running the Xray Core on a Router or Secondary Gateway: Deployment Options and Trade-offs

An overview of ways to run the Xray core directly on a primary or secondary router, comparing performance requirements, transparent proxying, and maintenance costs to help you decide whether deployment is worthwhile.

If only one computer needs a dedicated setup, deploying on that machine is usually easier to test and restore. Before moving the configuration to a gateway, decide which devices should be affected, who will restore the network if something fails, and how you'll verify that LAN services can still communicate. The hard part is often not starting the core, but making sure the traffic interception scope matches your expectations.

/ Getting Started

How to Choose V2Ray Nodes: Comparing Latency, Traffic Multipliers, Regions, and Protocols

A beginner's guide to choosing from dozens of subscription nodes, covering latency tests, traffic multipliers, regional use cases, and differences between VMess, VLESS, and Trojan.

First rule out regions or billing options that don't fit your needs, then compare candidates on the same network. Consider both response time and reliability instead of relying on a single speed-test ranking.

/ Routing

Custom V2Ray Routing Rules: domain, ip, and geosite Syntax and Match Priority

A practical breakdown of domain, full, regexp, ip, geosite, and geoip syntax, explaining top-down rule matching and how to handle common conflicts.

Change one rule at a time, then test both a destination that should bypass the proxy and one that should use it. This makes it easier to spot when a rule matches a broader range than expected.

Browse all articles →