Open-Source Client Guide

V2Ray Android v2rayNG Setup Guide

Choose an open-source client for your platform, then follow the setup guide to import subscriptions, grant VPN permission, and set up per-app proxying.

  • VLESS
  • VMess
  • Trojan
  • REALITY

PLATFORM / CLIENT

Download a V2Ray client for your platform

Choose your operating system first, then check the processor architecture and package format. The client imports configuration and establishes connections; after installation, you’ll also need to import a subscription or individual configuration. If you already have a working subscription, you can usually import it again on a new device instead of copying nodes one by one. However, review your per-app list, local ports, and routing rules on the new device.

Windows

Choose the v2rayN desktop edition or the classic WPF edition. If you’re new to v2rayN, start with the desktop edition. If a guide you’re following uses the classic interface, choose WPF to match its menus. Back up your configuration before switching editions, including subscription groups and custom rules. Then close the old app to avoid both windows changing the system proxy at the same time.

macOS

Check your processor under About This Mac. Choose the arm64 package for Apple silicon or x64 for an Intel processor. After migrating your configuration, check the client’s system proxy setting. The system proxy status and other apps’ proxy settings won’t transfer with your subscription.

Android

v2rayNG is usually the best place to start. Choose v2flyNG if your configuration specifically requires the V2Fly core. If your device supports 64-bit ARM apps, select arm64; if you’re unsure about the architecture, try the universal build. If you already have a client installed, distinguish an in-place update from switching apps: switching apps usually requires granting VPN permission again.

Linux

v2rayN offers deb and rpm packages. Choose the format used by your distribution’s package manager, then select x64 or arm64 for your processor. Test the connection in the client after installation. Desktop environments and apps handle system proxy settings differently, so if a particular app isn’t proxied, check its network settings first.

Not sure which of the three clients to choose? Compare platform support, cores, and routing features, or browse all client downloads →

SETTINGS / ANDROID

v2rayNG settings and configuration paths

Start by separating three layers: the system VPN determines which traffic reaches the client; per-app proxying determines which apps are included or bypassed; routing rules choose the outbound route for traffic that has reached the client. For example, if a browser is excluded, changing domain rules won’t bring it back into the VPN. Check the per-app list first if you want routing rules to apply to it. The paths below help you locate settings; they’re not a preset combination of switches to copy.

Route all traffic through VpnService

The first time you start a connection from the v2rayNG home screen, Android displays a VPN connection request. Check the app name and tap “OK.” Unlike a desktop system proxy, Android’s VpnService routes eligible traffic through the client, so apps don’t need to be configured with a proxy address. The VPN icon in the status bar only means a local tunnel is active; it doesn’t confirm that the remote node is reachable. If another VPN is running, disconnect it in system settings before connecting in the client.

Home screen → Start connection → System “VPN connection request” → OK

If you need to adjust several settings, verify each one using the relevant advanced configuration topic. Keep the basic connection working before changing routing or DNS. That way, if something goes wrong, you can undo the latest change instead of rebuilding the whole configuration.

QUICKSTART / THREE STEPS

Import subscriptions, connect, and verify

For your first setup, establish a basic connection before configuring per-app proxying, routing, or background operation. The steps below use v2rayNG as an example. Desktop clients follow a similar import sequence, but starting the client and enabling the system proxy are separate actions. If the connection drops or a particular app stops working, trace these three steps in reverse to determine whether the configuration was imported, the system is routing traffic through the client, and the remote connection is reachable.

  1. Import a configuration and select a node

    If you have a subscription URL, open “Subscription group settings,” create a group, paste the URL, and save. Return to the configuration list, tap “Update subscription,” then open the group and select a node. For an individual configuration link, use the list’s add menu to import it by source; don’t enter it as a subscription URL. If the list is empty, check that the URL was pasted in full, your current network can reach the subscription source, and you’re viewing the right group.

    If you already maintain a configuration manually, make sure the new entries are imported into a separate group. Give the group a distinctive name so you can tell new and old sources apart. If entries have the same display name, check which group they belong to before deciding what to delete.

  2. Start the connection and grant system permission

    Once you’ve selected an entry, start the connection from the home screen. When the “VPN connection request” appears for the first time, confirm it came from the client you just opened, then grant permission in the system dialog. If another VPN is in use, check what it’s for in system settings before disconnecting it; don’t disable a work configuration just to test. On desktop, start the client first and enable the system proxy if needed. Only apps that use the system proxy settings are affected by that switch.

    If the client immediately returns to a disconnected state, check whether the system allows VPN connections and whether the selected node still exists, then review the startup logs. Switching several nodes or changing DNS at the same time will usually make the cause harder to identify.

  3. Verify the connection with a real request

    In an app that should use the proxy, visit a page that normally loads and then check the client logs. The VPN icon only confirms that the system tunnel is active. A successful connection test to a remote port doesn’t prove that the app’s DNS lookup or page request is working. If something fails, first determine whether all apps are affected or only one app or type of domain.

    If only one app fails, check whether it’s excluded in the per-app list, then review its own proxy settings. If all apps fail, make sure your underlying network is working, then test the same node over Wi-Fi and mobile data separately. Change one condition at a time and note the test time and error category in the logs so you can compare results.

PROJECT V / CORE LINEAGE

The Project V ecosystem and open-source clients

The client, core, and server configuration are three distinct layers. The client handles importing, switching, and system integration; the core handles protocols, resolution, and forwarding; the server configuration determines the parameters used at both ends of the connection. Switching graphical clients doesn’t change a node’s protocol or convert the existing server settings.

From Project V to independently developed cores

The Project V ecosystem grew around modular network proxy tools. V2Ray handles core traffic forwarding, with configurations separating inbound, outbound, and routing so local traffic reception can be configured independently of the remote connection. The V2Fly community continues V2Ray’s maintenance and development; Xray evolved from the existing V2Ray core and is maintained on its own schedule. The projects share some configuration concepts, but they’re released independently by different communities. Updates from one project don’t determine how the other behaves.

This distinction is useful when troubleshooting: if you can’t find a button, check the graphical client’s interface guide. If the logs report an unrecognized field, check whether the core supports it. If both sides can read the configuration but the connection still fails, verify the server address, transport, and security parameters.

A protocol name isn’t a complete configuration

Open-source projects publish protocol documentation and implementations that can help explain why the same configuration behaves differently across cores. VMess, VLESS, and Trojan each have distinct configuration requirements. REALITY handles transport security; it isn’t an interchangeable alternative to these proxy protocols. When choosing a client, first identify the protocols, transport, and security mechanisms required by your configuration, then confirm that the client and core support those fields together.

When migrating, distinguish between “the link imports” and “the connection works.” The first means the client can at least parse the input; the second also depends on core behavior, parameters on both ends, and the current network. If you encounter an unfamiliar field, start with the concept reference to identify its layer, then decide whether to check the client settings or the core documentation.

What each client is for

v2rayN, v2rayNG, and v2flyNG are all open-source graphical clients. v2rayN is designed for desktop and provides subscription management, a local proxy, and system proxy controls; supported cores and modes depend on the specific build and configuration. On Android, v2rayNG uses the Xray core and Android’s VpnService to manage which traffic is routed. v2flyNG is an Android option based on the V2Fly core, suited to setups that need to match V2Fly configuration and behavior.

Before switching between the two Android clients, check where your configuration came from and which core it requires, then note your per-app list and routing preferences. These settings are stored locally in the client; saving the subscription URL alone won’t restore them. If both clients are installed, disconnect the active VPN before starting the other one so you can tell which app is routing your traffic.

Client, core, and subscription updates are separate

A client update can move menus or affect system compatibility; a core update can add fields or change defaults; a subscription update rereads configuration entries from its source. These are independent actions. If a node disappears after updating a subscription, check the list returned by the source first. If a configuration error starts after updating the client, inspect the core and the field causing the problem instead of blindly overwriting the existing group.

Before making changes, note the group, connection mode, and key routing rules for a configuration that currently works. After updating, test that configuration before trying new features. If you need to investigate further, record whether the failure occurs during import, startup, or a request. Before sharing logs, hide account identifiers, full subscription URLs, and node credentials; keep only the error details needed to identify the problem.

FIELD NOTES

V2Ray Technical Notes

View all articles →