Start with desktop v2rayN, or choose WPF if your guide uses the classic interface. Check Settings → About → System type before downloading.
If the app closes before opening a window, check the release notes for runtime requirements.
DownloadOpen-source clients for Android and desktop
Choose v2rayN for desktop and v2rayNG for Android. Start by picking the right installer, then import a subscription and configure routing.
First identify where the problem occurs. Updating a subscription retrieves configuration; enabling the system proxy changes how some apps connect; routing rules determine where traffic entering the client goes. These steps are not interchangeable. When troubleshooting, change one setting at a time and retry with the same app to see which change made a difference.
Routing rule example: when a destination matches the private IP list, send it through the outbound tagged direct. This tag must match the name of an existing outbound.
{
"type": "field",
"ip": ["geoip:private"],
"outboundTag": "direct"
}
Subscription groups are useful for managing connection configurations that change over time; a single link is better when you only need to import one configuration. In desktop v2rayN, save the URL under “Subscription groups,” then update the current group. In Android v2rayNG, open subscription group settings from the side menu, save the URL, and return to the main list to update. Make sure the new entries appear in the right group, then select a configuration to connect. If refreshing overwrites custom entries, save them in a separate group instead of editing subscription entries repeatedly.
Routing rules apply to requests that have already entered the core. They use the domain or destination IP to decide whether traffic connects directly or goes through a proxy outbound. This is separate from enabling the system proxy. Start by testing a request that should connect directly with the existing preset, then look for the matching rule under “Routing Settings.” Rules are generally evaluated in order, so put narrow exceptions before broader rules. If a domain rule does not take effect, check whether the client sees a domain or an IP address before changing DNS behavior or match conditions.
In v2rayN, “Set system proxy automatically” configures the operating system's proxy for desktop apps that respect that setting. This differs from Android, where a system VPN service routes app traffic, and it does not guarantee that every desktop process uses the same proxy. To test it, make a new request in a browser and check whether the client logs the connection. If an app has its own network options, check where it gets its proxy settings. When the test is done, select “Clear system proxy” to remove the proxy setting applied by the client.
In v2rayNG's VPN mode, “Per-app proxy” lets you choose which apps use the VPN. After enabling it, check whether the app list controls inclusion or exclusion. With “Bypass mode” on, selected apps bypass the VPN. Save your changes, disconnect, and reconnect, then test with new requests from selected and unselected apps. The app list controls which apps enter the VPN; routing rules determine which outbound they use. Different domains in the same app may use different outbounds.
The core interprets connection configurations and establishes sessions; the client provides the interface and system integration. Desktop v2rayN lets you choose a compatible core for supported configurations. On Android, switching from an Xray-based setup to a V2Fly-based one usually means choosing a different client. Before importing, check the protocol, transport, and security options used by the server—not just whether the link is recognized. For REALITY configurations, choose a core that supports REALITY. If fields produce errors after switching, compare them with the original configuration rather than deleting fields one by one to force a startup.
This interface preview brings settings together for comparison; it does not represent the actual menu order. If your client uses different labels, start with Concepts at a glance. Identify whether you need to change the traffic entry point, destination matching, or the connection configuration itself, then open the relevant menu.
First decide which device you are installing on, then check its operating system and processor architecture. Packages for the same architecture are not interchangeable across operating systems. If the app is already installed, check which client and release type you have before updating.
Start with desktop v2rayN, or choose WPF if your guide uses the classic interface. Check Settings → About → System type before downloading.
If the app closes before opening a window, check the release notes for runtime requirements.
DownloadCheck “Chip” or “Processor” in “About This Mac,” then choose the Apple Silicon or Intel package accordingly.
Move the app to Applications as directed and launch it there, not from the disk image.
DownloadChoose v2rayNG unless you need V2Fly. Most newer devices support arm64. If unsure, check the requirements for the universal package.
If an update fails, back up subscriptions and manually added entries before uninstalling.
DownloadChoose deb for Debian or Ubuntu, or rpm for Fedora. Check that the package matches your CPU architecture.
Check the desktop proxy settings and test with an app that uses them. Some apps need separate configuration.
DownloadFor your first connection, keep the default settings and establish a baseline with a configuration you know works. Once connected, adjust routing, per-app selections, or background settings. If something goes wrong, you can return to the previous step and test again.
If you have a subscription URL, create a group in the client, enter a name you can recognize and the URL, save it, then update the group. If you only have one share link, use the import-from-clipboard option; there's no need to create a subscription first. After importing, check that the expected entry appears in the main list and select one to test. If the client reports that no configuration was found, make sure you copied the full URL or share link—not the text next to a QR code. Subscription URLs may contain access credentials, so don't include the full URL in public screenshots or support requests.
On desktop, select a configuration in v2rayN, choose “Set system proxy automatically,” then open a browser that uses the system proxy. On Android, tap Connect in v2rayNG. When Android first asks to authorize the system VPN, check which app initiated the request before granting access. Don't change the per-app list during the test, and check that no other VPN is using the system connection. If an error occurs before enabling the proxy or granting system access, troubleshoot app startup, runtime requirements, or permissions first—not routing rules.
Open a page you visit regularly, make a new request, and note the time. Then check the client's runtime log for an entry at that time. If there's no matching entry, check whether the test app is using the client. If the log shows a direct connection that should have used a proxy, inspect the matching rule. If a connection attempt times out, check your local network, connection configuration, and server status in that order. When testing is complete, restore the original system proxy setting or disconnect the Android VPN, then retry in the same app to confirm the connection changes as expected.
Projects, cores, and clients are three distinct layers. Identify which one the documentation refers to before deciding whether a feature belongs to a connection protocol, a core implementation, or a client setting.
Project V is the project ecosystem that V2Ray originally belonged to. The V2Ray core handles inbound connections, outbounds, and routing. The V2Fly community continues to maintain the V2Ray core, while Xray branched from the same code lineage and has evolved independently. In everyday use, “V2Ray” can mean the core or serve as a general term for this category of tools. When a guide says “V2Ray compatible,” check whether it means the client can import a particular share-link format or actually connect using the required protocol and transport settings.
The two core families share some configuration concepts, but using the same protocol name does not mean all transport and security settings are compatible. Check the protocol separately from any additional fields: a VLESS configuration, for example, may also require specific transport or security options. If a client can display an imported configuration but fails to start or complete a handshake after a core switch, compare each field against the supported options and confirm what the server expects. An imported configuration is not necessarily a compatible one.
v2rayN is for desktop and manages subscriptions, settings, and the system proxy. v2rayNG uses an Xray-based core to route Android app traffic through the system VPN service. v2flyNG uses a V2Fly core and offers another option for Android users with compatible configurations. All three GUI clients are released under the GPL-3.0 open-source license and are free to use. The client license does not determine the licenses for the core or other components, and does not include a working server or subscription service. Choose a client based on the settings in your configuration.
Clients, cores, and routing rule data may be updated separately. A client update can affect the interface or system integration; a core update may change how configurations are parsed and connections behave. If only a few domains use the wrong outbound, check the active routing rules and data before changing both the client and core. Before updating, note the active group, routing preset, and app scope. After updating, test a connection that worked before, then try the new configuration to distinguish migration issues from existing problems.
A window that won't open, a single connection that times out, and a handshake error in the logs each call for a different starting point. Choose the guide that best matches what you're seeing. If multiple apps are affected, work through the symptoms in Troubleshooting.
For clients that crash or close on startup, check the .NET Desktop Runtime, extraction path and folder permissions, security software blocks, and corrupted configuration files. Includes steps for Android crashes, too.
Troubleshoot connection timeouts and failures step by step: check your device's system clock, port conflicts, system proxy mode, subscription settings, transport layer, and TLS settings, with checks for each.
Explains log levels and log structure, then breaks down common errors such as connection refused, i/o timeout, and tls handshake failure, with suggested next steps for each.