Open-source clientsProject V

V2Ray Client Downloads

Choose a graphical client for your system, start by importing a subscription, then check each symptom if the connection fails.

Common V2Ray client settings

Seeing a node only confirms that it was imported. Whether an app uses the proxy, the core can complete a handshake, and requests are routed by rules are controlled by separate settings. Use the scale below to match your symptom to the right layer.

Protocols, transports, and security settings

If a node imports correctly but the handshake keeps failing, first check that the protocol, transport, and security layer match the server. VMess, VLESS, Trojan, and Shadowsocks use different settings, and the same protocol can use different transports. In desktop clients that support multiple cores, open the node editor to review its settings, then confirm which core is actually enabled. Unlike single-protocol tools, multi-protocol clients make it easier to manage everything in one place, but switching cores does not rewrite existing settings. Change only the setting you have confirmed is wrong, then test a real connection again.

Related troubleshooting: No internet access →
Node editor · What to check
  • Protocol
  • Transport protocol (network)
  • Transport security (security)
  • Server name (serverName)

Choose an installer for your system

If the app will not open, first check your OS, processor architecture, and package format—not the node. Installation and connectivity are separate steps. Get the client opening and its settings page working before importing a configuration to troubleshoot the network.

Windows

Choose the v2rayN desktop edition or classic WPF edition. The desktop edition uses a cross-platform interface; if you are used to the older menus or following instructions for them, see the WPF option. Check your system information to confirm whether you have x64.

If the release package needs extracting, extract it fully to a directory you can write to before launching the app. If a runtime warning appears, note the missing component and install it as described on the download page, then try again.

Go to downloads

macOS

Choose the v2rayN package for your chip. Check About This Mac for your processor: Apple silicon uses arm64; Intel uses x64. The OS version alone does not tell you the architecture.

After installing from a disk image, launch the client again from Applications. If macOS displays a warning, first determine whether it concerns an incompatible architecture, a minimum OS version, or permissions; each requires a different fix.

Go to downloads

Android

The usual choice is v2rayNG, based on Xray. If you specifically need V2Fly compatibility, consider v2flyNG. First check which app architectures your device supports: choose arm64 if supported, or use the universal package if you are unsure.

Complete the initial VPN authorization while the app is in the foreground. If connections drop only after switching networks or locking the screen, test the same node again, then check for other active VPN sessions and background battery restrictions.

Go to downloads

Linux

First check which package format your distribution uses: Debian- and Ubuntu-based systems typically use deb, while Fedora-based systems typically use rpm. Then check system information to identify x64 or arm64; these architectures are not interchangeable.

This download is a graphical client. Installing it does not guarantee that your desktop environment will route every app through its proxy settings. After setup, test with a browser, then check whether the affected app inherits the desktop proxy.

Go to downloads
View all clients →

Import a subscription, connect, and verify

For your first setup, test one connection path: one device, one network, one node. Note what happens at each step so you can reproduce a successful setup or pinpoint a failure—even if you switch devices later.

  1. Import a subscription and confirm the nodes appear

    In desktop v2rayN, add a subscription group and save its URL, then update the group manually. In v2rayNG, add it through subscription group management and run an update too. When nodes appear in the list, confirm they belong to the group you just updated so you do not mistake old nodes for newly imported ones.

    If the node count does not change, check the update message. For a timeout, check how the URL is being accessed; if the format is unsupported, check the subscription type. Subscription URLs may contain access credentials, so hide the full URL in troubleshooting screenshots.

  2. Select a node and enable the connection

    Choose a node from the newly imported group that is compatible with the client core. On desktop, confirm it is the active configuration, then enable the system proxy. On mobile, start the connection and approve the system VPN prompt. For the first test, keep the default rules and do not add custom routing or DNS settings.

    If the connect button quickly returns to a disconnected state, check the first error in the log. A port conflict, unrecognized configuration, and failed handshake are different problems. Fix startup errors before testing access.

  3. Check the request path in the same app

    Send a new request from a browser that uses the system proxy, and note whether access works before and after connecting. If needed, compare the exit IP and client logs. A node's latency test can succeed even when the browser's traffic is not using the same route.

    If only one site fails, test another destination expected to use the same outbound in the same browser, then check rule matching and DNS resolution. If access also fails with the proxy off, restore basic network connectivity first; do not change multiple nodes and rules at once.

Read the full guide →

How Project V, V2Fly, and Xray fit together

Projects, cores, clients, and node protocols are different layers. Before following a guide or reporting an issue, identify which layer it concerns. In particular, if an error occurs during startup, the name shown in the interface does not necessarily identify the core that is actually running.

Project lineage
Project V
Core families
V2Fly / Xray
Graphical clients
v2rayN / v2rayNG / v2flyNG
Quick reference →
  1. Understanding modular proxy design through Project V

    V2Ray originated with Project V. It separates inbound connections, outbound routing, and the rules that direct requests into distinct configuration components. An inbound accepts requests from a browser or another app and passes them to the core; routing selects an outbound based on conditions; the outbound handles direct connections, proxying, or other actions.

    These three components also map to common symptoms. If the core receives no connection, check local proxy access. If a connection reaches the core but takes the wrong route, check rule order. If the request reaches the expected outbound but still fails, check server settings and network reachability. Identifying the layer is more reliable than guessing based only on a webpage that will not load.

  2. V2Fly and Xray have different compatibility ranges

    The V2Fly community continues the V2Ray core project. Xray branched from the same code lineage and has evolved independently; each is maintained by its own community. Their configuration concepts often overlap, but supported transports, security layers, and fields can differ. Using the same protocol does not guarantee that both cores accept the same complete set of settings.

    If a node imports but the core will not start, first check which field the log identifies. Then determine whether the core does not support that option or the client omitted it when generating the configuration. Note the original core before switching. To compare results, keep the same node and network so you can tell which layer caused the difference.

  3. Open protocol implementations do not make settings interchangeable

    VMess, VLESS, Trojan, and Shadowsocks all have implementations in the open-source proxy ecosystem. A protocol defines how the two ends exchange data; the transport and security layer determine how that data is carried and protected. For example, the VLESS protocol name alone does not mean TLS is configured, and TLS is not the same thing as a transport.

    When reviewing a shared node configuration, check the protocol first, then compare the transport and security layer with the corresponding fields and server settings. Copying a single setting from another guide can make two previously matching configurations inconsistent. Open protocols make implementations easier to compare and troubleshoot, but that does not mean a subscription or third-party service is part of the client project.

  4. Three open-source clients for graphical configuration

    v2rayN is a desktop graphical client for managing nodes, subscriptions, and routing, with a choice of supported core. v2rayNG uses Xray and provides mobile subscriptions and VPN connections; v2flyNG uses V2Fly and is suited to mobile configurations that need confirmed V2Fly compatibility. All three are open-source clients: their interfaces organize settings, while the underlying core establishes the connection.

    Subscription services and clients are separate. Installing a client does not provide nodes, and a client opening successfully does not mean a subscription is still valid. Remote errors, expired nodes, and missing app permissions require checking the subscription source, node configuration, and device settings respectively. Identify which side produced the error before choosing the relevant part of a guide.

  5. Clients, cores, and subscriptions update on different schedules

    A client update may change the interface, system support, or packaging. A core release may add fields or fix connection behavior. Refreshing a subscription only syncs the node list provided by its source. A successful subscription update does not replace a software upgrade, and reinstalling the client will not restore an expired subscription.

    Before upgrading, back up custom routing and configuration, and note the current core and connection mode that works. After upgrading, test the original node first, then restore optional settings one at a time. If a regression occurs, record when it started, the platform and architecture, selected core, reproducible steps, and redacted logs. That is more useful for diagnosis than a screenshot that only shows a failed connection.

Guides to subscriptions, connections, and proxy modes

Choose an article based on where the problem occurs: for a failed subscription update, check retrieval and parsing; if a node appears but the first connection fails, check the node and outbound path; if only some apps behave differently, distinguish system proxy issues from routing.

View all articles →