Skip to main content
Choose a client · Configure subscriptions · Troubleshoot connections

V2Ray Client Downloads v2rayN Setup Guide

Download v2rayN View the guide

Start with subscription import, then set up routing and TUN mode in order.

  • VMess
  • VLESS
  • Trojan
  • REALITY

CLIENT WORKFLOW

Subscriptions, routing, and traffic capture

Import nodes into the client first, then decide which traffic should reach the core. The interface manages configuration; the core establishes connections. System proxy and TUN determine how app traffic gets to the core. Check these layers separately to pinpoint issues more easily than by changing several switches at once.

A subscription URL provides a set of node configurations; it is not the same as a share link for a single node. In Subscription Group Settings, create a group, enter a label and URL, save it, then select Update subscription (no proxy). If the URL is unreachable on your current network and you already have a working connection, try updating through the proxy. Create separate groups for different sources to make updates and troubleshooting easier. Subscriptions simplify centralized node management compared with entering each node by hand, but check the logs and node list to confirm an update succeeded.

Routing rules choose a direct or proxy outbound based on criteria such as domain names and destination addresses. In Routing Settings, choose rules suited to your network, then check the default outbound. Enabling the system proxy does not mean all traffic uses the same route. Keep private-address rules set to direct if you need access to local devices. Routing can handle different destinations separately, but rule order and DNS resolution affect which rules match. After making changes, test the same app again and check the logs to confirm which outbound was selected.

The system proxy mainly affects apps that honor the system proxy settings, making it a good first step for testing browser connectivity. TUN captures traffic through a virtual network interface and works with apps that ignore system proxy settings, but requires the right permissions and routing support. Get a standard proxy connection working before enabling TUN mode, so node issues don't get mixed up with virtual adapter issues. TUN captures more traffic than the system proxy, but can also be affected by other virtual adapters, DNS settings, and networking tools. After exiting, check that the system network settings have been restored.

The core parses configuration and handles connections. Fields with the same name in a graphical interface are not necessarily supported in the same combinations by every core. In v2rayN Settings, check the core selected for the relevant configuration type, then choose Xray or sing-box based on the node protocol and transport requirements. Note the current selection before switching and check the startup log afterward. Multiple cores offer more flexibility than a client with a fixed core, but switching cores won't fix invalid credentials or a dead node. For specific security features, confirm that both the client and core support the required fields.

v2rayN · Subscription Management

Subscription Group Settings

LabelName by source
Subscription URLEnter the full URL
First fetchUpdate subscription (no proxy)
When completeCheck the update log
Group → Update → Select an active node

First-time setup: test one layer at a time

After importing, select a node, set it as the active server, and check that the core starts. Seeing a node in the list only confirms that its configuration was loaded; it does not mean the remote server is reachable. Keep the log panel open while testing and note whether the error occurs at startup or when accessing a destination. These point to different things to check.

Next, enable the system proxy and use a browser to visit a known test destination. If the browser works but another app doesn't, first check whether that app uses the system proxy; don't reinstall the client right away. To capture more traffic, read the sections on TUN permissions and DNS. Menu names may vary slightly across operating systems and interface versions, so look for the relevant feature. For the full walkthrough, see the quick-start guide.

Keep subscription URLs and node settings separate

Subscription URLs often contain access credentials and should be treated like account information. Before sharing a screenshot, hide query parameters in the URL and any node identity fields. If a subscription won't update, check that the URL is complete and hasn't expired, and that the response isn't a login page. Whether an imported node can connect is a separate question. These two paths can fail independently, so don't use the result of one to judge the other.

PLATFORM SELECTOR

Choose a client for your operating system

For desktop, start with v2rayN. On Android, consider v2rayNG first, then look at v2flyNG if you specifically need its core. The download page lists architecture options and installation instructions. A client reads and runs configuration; after installation, you'll still need a working subscription URL or node settings.

Windows

Recommended: v2rayN

The download page offers a desktop edition and a classic WPF edition. The desktop edition uses a cross-platform interface, while WPF keeps the classic layout. Choose whichever suits your workflow; there's no need to install both just to use the same subscription. Check your operating system and processor requirements before installing. After the first launch, find Subscription Group Settings and import your configuration.

If you need TUN, follow the client's instructions to check administrator permissions. If your network drops after enabling it, turn TUN off first and confirm the system proxy works, then check the virtual adapter and other networking tools. After exiting the client normally, confirm the system proxy settings have been restored as expected.

Download Windows client →

macOS

v2rayN

Check your chip in About This Mac, then choose the Apple Silicon or Intel download. Architecture determines whether the app runs as expected; it does not change how subscription URLs are written. Move the app to the Applications folder, launch it, then import your subscription and select an active node.

If macOS shows a security alert, read it and verify the app's source. Use the relevant option in System Settings rather than disabling security features altogether. For your first connection, test the system proxy. If you need TUN, grant the requested permission and check the network extension or virtual interface status. See the complete installation guide for menu details.

Download macOS client →

Android

v2rayNG / v2flyNG

v2rayNG uses the Xray core and is the recommended starting point. v2flyNG uses the V2Fly core and is suited to configurations that specifically require it. Most recent devices can use arm64; if you're unsure of your architecture, check the universal build details. Don't assume the two apps support exactly the same protocol combinations just because their names are similar.

Add a subscription, update it, select a configuration, then tap Connect and approve the system VPN prompt. If the connection often drops in the background, check battery optimization and background activity limits. If the connection is established but some apps still fail, check their routing settings. While troubleshooting, avoid running other tools that use the VPN interface.

Download Android client →

Linux

v2rayN

Choose a deb or rpm package based on your distribution, then check whether you need x64 or arm64. Package format and processor architecture are separate requirements; check both. After installing, launch the app from your desktop environment, test a standard proxy connection, then configure TUN permissions and system services if needed.

Not all apps read the desktop environment's system proxy settings. If a browser connects but other apps don't, check each app's own proxy options first. If DNS resolution fails after enabling TUN, check how your system manages DNS and whether other virtual network interfaces are active. Avoid repeatedly changing DNS in multiple settings panels, so you can reproduce your tests.

Download Linux client →
Browse all clients → Compare the three clients → View installation guides for all platforms →

PROJECT V / V2FLY / XRAY

Open-source projects and core compatibility

Client names, protocol names, and core names refer to different layers. Understanding how they relate helps you choose the right software and explains why the same configuration can behave differently across clients.

Project V: Configuration model and tooling

Project V is an ecosystem of network proxy tools, with V2Ray as one of its key components. Inbounds receive local traffic, outbounds connect to destinations or remote servers, and routing rules choose between them. Subscription managers and GUI clients make these configuration capabilities easier to use; they don't rely on a separate connection model unrelated to the core.

Importing a subscription, selecting a node, and enabling the system proxy are three different actions. A subscription provides configuration; the active node determines which remote settings are used; the system proxy or TUN determines where traffic enters. Check each link in this chain to troubleshoot, rather than treating every issue as simply “the client won't connect.”

V2Fly and Xray: shared roots, different paths

The V2Fly community continues the development and maintenance of V2Ray, while Xray forked from related code and has evolved in its own direction. They share some concepts and protocol background, but their configuration fields, transport support, and feature development are not interchangeable. For VLESS, XTLS Vision, REALITY, and other requirements, check support in the specific core you're using instead of relying on similar-looking fields in the interface.

When migrating a configuration, identify the original core first, then check which fields the target core accepts. An unknown-field error indicates a configuration compatibility issue; a connection timeout may occur at the network, remote server, or handshake stage. These errors call for different troubleshooting steps, and core names alone don't indicate connection quality.

Three clients: GUIs and open-source licenses

v2rayN, v2rayNG, and v2flyNG are open-source projects with graphical configuration interfaces for desktop and Android. v2rayN supports managing multiple cores; v2rayNG is based on the Xray core; v2flyNG uses the V2Fly core. Choose a client based on your platform and configuration needs, then consider whether you require a particular interface or core feature.

Open-source licenses define conditions for using and redistributing code; related components don't necessarily share the same license. V2Fly's main code is licensed under MIT, while Xray's main code uses MPL 2.0. Clients and their dependencies have their own license terms. For everyday use, focus on feature compatibility. If you modify, package, or redistribute software, read the relevant license texts separately.

Updates: check the interface, core, and rules separately

Client updates can change menu layouts and how configurations are generated. Core updates can change supported fields, while routing data updates can affect domain or address classification. When something changes, identify which layer was updated before deciding whether to migrate settings. Upgrading the client shouldn't be the default fix for every connection problem.

Keep a record of your configuration before updating. Afterward, retest with a node that worked before and the same destination. If only one protocol combination fails, check the core startup and handshake logs. If only some destinations use the wrong outbound, check the routing rules and their order. When sharing logs, include only what's needed for diagnosis and hide subscription URLs and identity fields. This site provides independent setup guides and does not replace the upstream projects' license or feature documentation.

Explore the project →

CONFIGURATION NOTES

Configuration and troubleshooting

Use the specific error in the logs to guide your next steps. If the core won't start, check ports and configuration fields. If the core starts but connections fail, check the handshake and certificates. To understand how the configuration fits together, start with inbounds, outbounds, and routing. Change one thing at a time and keep a record of the results before and after.

Troubleshooting

V2Ray TLS Handshake and Certificate Errors: System Time, SNI, and allowInsecure

For expired certificates, x509 errors, or handshake timeouts, check your system date and time zone first, then confirm that the SNI matches the server's requirements. This guide distinguishes certificate validation failures from network timeouts and explains why skipping certificate checks is not a routine fix. Troubleshoot by error type to avoid masking the underlying configuration issue.

View TLS troubleshooting steps →
Browse all articles → Back to the quick-start guide →