Open-source client directory

V2Ray Chinese Sitev2rayN downloads and setup

Choose an open-source client for your platform. Start with subscription import, then explore routing and core configuration.

01 Configuration walkthrough

Client settings and JSON fields

The client manages subscriptions and starts the core; the configuration file tells the core how to accept, inspect, and forward traffic. The snippets below illustrate individual fields and are not complete, runnable configurations.

Subscriptions and a local inbound

Subscriptions let you update multiple nodes at once. In v2rayN, add a subscription URL, update its group, then choose a node from the refreshed list. Seeing entries in the list only means the client has read the configuration; it does not confirm that the server is reachable. A subscription URL is client management data, not a core JSON field. The SOCKS inbound below is a local proxy endpoint for apps on your device after the core starts; it is separate from the remote subscription URL. If you configure an app's proxy manually, use the port shown in the current settings.

{
  "inbounds": [
    {
      "listen": "127.0.0.1",
      "port": 10808,
      "protocol": "socks"
    }
  ]
}

View the JSON manual

02 Download clients

Choose a client for your OS

Start with the device's operating system, then check its CPU architecture. Choose v2rayN for desktop devices; for mobile devices, pick v2rayNG or v2flyNG based on the configuration requirements.

The v2rayN downloads here include an x64 desktop edition and the classic WPF edition. The desktop edition uses a cross-platform interface, while the WPF edition retains the classic interface. They are different graphical apps, not clients for different node protocols. Open your system's About page to check the system type and confirm which build your device can run.

When migrating from an older installation, quit the existing app before launching the new one. If two clients on the same machine use the same local listening port, the second one may report that the port is already in use. After switching, check that the system proxy still points to the address and port the current app is actually listening on. If startup fails, first determine whether the interface app failed to launch or whether the core failed to start after the interface opened, then check the relevant error message.

Check the chip or processor information in About This Mac. For a device with an Apple chip, choose the Apple Silicon arm64 build; for an Intel processor, choose x64. These options differ by CPU architecture, not by subscription protocol. Don't guess based on the device's appearance.

After opening the disk image, move the app to Applications before launching it so you can open it from a consistent location later. For the first test, use a browser that respects the system proxy and avoid changing multiple network options at once. Proxy settings for Wi-Fi and Ethernet may belong to different network services. If behavior changes after switching networks, check the settings for the network service in use rather than reimporting the subscription.

Most recent devices can use the arm64 build, provided the OS supports apps built for that architecture. If you're unsure, try the universal build. It typically includes native libraries for multiple architectures, but the client must still meet its own system requirements. v2rayNG uses the Xray core; choose v2flyNG when you need to check behavior against V2Fly.

The first time you use VPN mode, the system will ask you to approve the connection. If another app has already set up a VPN on the device, check for a conflict. Once connected, if a particular app behaves differently, check whether per-app filtering is enabled and whether that app is included or excluded. Installation architecture is rarely the issue at this stage; architecture problems usually occur during installation or when native libraries are loaded.

Choose the package format for your distribution, then select the device architecture. Distributions using the Debian package system generally need deb; those using the RPM package system generally need rpm. Both formats have x64 and arm64 builds. A matching package format does not guarantee the architecture is right, so check both separately.

If the package manager reports missing dependencies or incompatibilities, note the message and resolve the issue during installation before launching v2rayN. Once running, whether a desktop app uses the system proxy depends on the desktop environment and the app itself. If a browser works but a terminal does not, check the terminal tool's proxy options or environment settings separately; don't mistake a terminal bypassing the proxy for a failed installation.

View all clients

03 First-time setup

Import, route, and test a connection

For your first test, use one node, one routing setup, and one app. Confirm the basic connection first, then enable other connection methods or adjust DNS.

  1. 01 Subscription source

    Import a subscription

    Once you have a subscription URL, add and save an entry in a subscription group, then update that group. Saving the URL and fetching its entries are separate steps. If the list is still empty, make sure you selected the group you just added and check the update result. If you have a single node share link, use the import option for an individual node.

    After importing, start with one node whose protocol and transport settings are clear. If the update fails, check whether the URL was truncated or has extra spaces. If the update succeeds but only a few nodes are missing, check whether those nodes use a format the client supports. Hide subscription URLs, account details, and node credentials in screenshots shared for troubleshooting.

  2. 02 Outbound rules

    Choose a routing mode

    First decide which traffic should connect directly and which should go through a proxy node. If you use a preset in the client, confirm which one is selected and check its matching conditions for direct and proxied destinations. A work network or local service can serve as a direct-connection test; choose a stable, known-to-be-accessible destination for the proxy test.

    The system proxy toggle controls whether some apps send traffic to the local inbound; the routing mode determines where the core sends connections it receives. Neither setting replaces the other. If local network access changes after editing rules, keep the same node and switch back to the previous rules alone. This helps determine whether the match conditions changed or the app started using a different inbound.

  3. 03 Live connection

    Connect and test

    On desktop, select a node and confirm the core is listening before enabling the system proxy if needed. On mobile, select a node, establish the VPN connection, and approve the system permission prompt. Use real apps to test both a direct destination and a proxied one, and check the client logs for the corresponding requests. Listed latency and connection status are no substitute for this test.

    If both tests fail, check the local inbound or VPN status first. If only the proxied test fails, check the node, routing match, and remote handshake. If you need command-line access after the browser test succeeds, test the target tool separately. Before quitting the client, turn off or clear the system proxy so other apps don't keep trying to connect to a local port that is no longer listening.

View the full guide

04 Open-source ecosystem

Project V, V2Fly, and Xray

First distinguish the interface, core, and protocol. The client name tells you which app to choose; protocol and transport settings determine connection compatibility.

Client
Manages subscriptions and nodes, and creates or loads configurations
Core
Reads the configuration and handles resolution, routing, and forwarding
Protocol
Defines how the two ends of a connection exchange data

About the project

  1. Project V and the role of clients

    Project V is a useful starting point for understanding the earlier V2Ray project. V2Ray defines traffic entry points, forwarding destinations, and matching rules separately: requests received by the same inbound can be routed to different outbounds. This structure makes it easier to inspect traffic capture separately from routing decisions, and gives different graphical clients a shared set of configuration concepts.

    v2rayN, v2rayNG, and v2flyNG are open-source graphical clients for managing nodes, configuring settings, and starting the core. Desktop interface settings are not the same as the core's configuration file; on mobile, VPN authorization is handled by the operating system. When researching an issue, first identify whether it lies in the interface, the OS, or the core. For example, an app opening normally does not prove the core is listening, and OS permission to use a VPN does not guarantee a successful remote handshake.

  2. Shared syntax and differences between V2Fly and Xray

    The V2Fly community continues development of the V2Ray core, while Xray developed from a fork of V2Ray's code. Both retain similar concepts for inbounds, outbounds, and many routing fields, but their implementations are independent. Even when fields have the same name, check support in the core you're using. This is especially important for newer transport and security options; don't assume parameters from one configuration will work in the other.

    When choosing a core, first confirm the node's requirements, then check which core the client can run. If a configuration that worked in an older setup now reports an unknown field or unsupported option, find the field name in the logs and determine whether the client generated an incorrect parameter or the target core doesn't recognize it. A minimal configuration with sensitive details removed is more useful for troubleshooting than repeated reinstalls. Compare common names in the core glossary.

  3. Check protocol, transport, and security separately

    VMess, VLESS, and Trojan all appear in this ecosystem, but each has different requirements for authentication, connection parameters, and the security layer. Protocol and transport describe different aspects of a connection: recognizing a protocol does not mean a client supports every transport combination a node might use. Even with the correct remote address and port, mismatched transport settings or server names can still cause a connection to fail.

    For example, VLESS does not provide encryption by itself. Check the security layer actually in use rather than inferring connection security from the protocol name alone. Open-source client and core code does not mean these projects operate third-party nodes imported into the software. Evaluate software source, connection settings, and node operator separately. See the protocol guide for definitions.

  4. Client, core, and subscription updates affect different things

    A client update may change the interface or how configurations are generated; a core update may affect supported fields; and a subscription update refreshes the node list in a group. They don't all need to happen at once. When investigating a recent change, note where the problem began: if the app won't start after an upgrade, check the core logs; if one node stops working after a subscription update, check that node's updated parameters first.

    When managing rules manually, keep a record of the active routing configuration, key tags, and local ports so you can compare them after changes. First use a known-working entry to test the proxy inbound and remote connection, then restore custom routing and DNS settings one at a time. Keep subscriptions and custom configurations containing credentials in a secure location. When reporting an issue, the error category and relevant field names are usually enough.

  5. Find help based on where the error occurs

    If the subscription list is empty, start with the import option, group selection, and update errors. If the list looks normal but no apps can connect, check whether the core started, whether its port is listening, and whether apps are sending requests to the local inbound. If only certain destinations fail, check routing matches, DNS resolution, or the remote connection. This order helps avoid changing nodes to fix a local connection issue or repeatedly changing the system proxy when a node has stopped working.

    For interface steps, see the Getting Started guide. To understand field values and structure, use the JSON manual. The inbound and outbound snippets in the manual only cover the parts discussed in each example. Before merging them into an existing configuration, check references to tags with the same name and the default outbound order, then test with real requests.

05 Practical tips

Installation, proxy modes, and node selection

Choose a guide based on the issue at hand: first check whether the client starts, then whether requests reach the core, and finally compare how nodes perform.

View all articles