Open-source clients / Setup guides

V2Ray Official Download SiteClient and Setup Guides

Download v2rayN View the guide

Use subscription management to organize connection profiles, routing rules to direct traffic, and system proxy or TUN mode as needed.

Project V ecosystemXray / V2FlyChinese-language guides
PLATFORMS
DESKTOP
v2rayN
MOBILE
v2rayNGv2flyNG
ROUTING
GeoSiteGeoIP
WORKFLOW
Import → Route → Verify

CONFIGURATION / WORKSPACE

Subscriptions, routing, and traffic capture

The GUI organizes your settings; the core handles connections. First confirm where your configuration comes from, then choose how traffic reaches the client, and finally check which rules match. The sections below explain common tasks. Examples illustrate how fields relate; they are not complete connection configurations.

configuration / notes

Save the subscription before updating it

A subscription consolidates multiple server configurations at one URL. Open the subscription group settings, enter a recognizable name and the URL, save, then update the subscription to load its configurations. Unlike pasting share links one at a time, groups make it easier to refresh entries and track their source, but an update may replace entries in the group. Keep manual changes before updating, then confirm which server is active. Subscription URLs may contain access credentials, so treat them as sensitive. When troubleshooting, note the error type without sharing the full URL.

Subscription URL format (example domain):
https://example.com/subscription

Steps:
Subscription groups → Add → Save → Update subscriptions

CLIENT / PLATFORM

Choose a client by platform

Check your processor architecture in system information, then open the matching download section. v2rayN is the desktop option; on Android, choose a client based on the core you need. Clients manage local configurations, but installing one does not provide a working server—you still need a subscription or configuration you are authorized to use.

Windows

v2rayN offers a desktop edition and a classic WPF edition. The desktop edition uses a cross-platform interface, while WPF retains the classic desktop experience. Check your OS and system requirements before choosing a package. After installation, keep the app and its configuration in a writable location so permissions do not prevent settings from being saved.

On first launch, import a subscription, select a server, then enable automatic system proxy configuration. If a browser connects but other apps do not, check whether those apps use the system proxy instead of assuming the subscription is at fault. For broader traffic capture, follow the guide to check TUN permissions.

Go to downloads

macOS

v2rayN packages are available for Apple Silicon and Intel Macs. Check your chip or processor under About This Mac and choose the matching architecture. Launch the app from your Applications folder. If macOS asks you to confirm that the app can be opened, verify its source, then approve it in the system security settings.

System proxy and virtual-interface traffic capture use different system mechanisms. For your first setup, test the regular proxy and check browser requests alongside the client log. If network extensions, permissions, or other connection tools conflict, note the current state and troubleshoot one change at a time rather than altering several network settings at once.

Go to downloads

Android

Start with v2rayNG, which uses the Xray core. If you need the V2Fly core, consider v2flyNG. Most recent devices use the arm64 package; if you are unsure of the architecture, check your device specifications or the universal package notes. Grant installation permissions only for the source you are using, and restore the settings afterward if needed.

Import the subscription and update it, select a configuration, then start the connection. The first launch requires system connection permission. Background connections may be affected by battery-saving settings, so allow the necessary background activity in your device settings. Stop the current connection before switching clients to avoid conflicts between traffic-capture services.

Go to downloads

Linux

v2rayN offers deb and rpm packages for x64 and arm64. Debian- and Ubuntu-based systems generally use deb; Fedora and similar distributions generally use rpm. Check your distribution's package manager for the right choice. First confirm the desktop app launches and its dependencies are met, then configure auto-start for your user session.

System proxy support varies across desktop environments, and some apps require their own proxy settings. After installation, verify the GUI, core startup, and app requests separately. TUN permissions and network routes also need separate setup; a successful installation does not mean traffic capture is working.

Go to downloads
View all clients →Read the complete cross-platform installation guide →

QUICKSTART / THREE STEPS

From subscription import to connection testing

Handle configuration, traffic capture, and verification separately. This makes it easier to identify which layer has a problem and restore a working setup if a change fails. The desktop steps below use v2rayN; menu labels may differ in v2rayNG on Android, but the sequence is the same.

  1. 01 / IMPORT

    Save a subscription and load its configurations

    Open Subscription Groups, add a name and the full subscription URL, save, then update. Query parameters at the end of the URL may be required for authentication, so do not remove them. If you copied the link from a chat or document, check for spaces, line breaks, or non-ASCII punctuation. Configurations appear in the server list only after the update completes.

    If the list is empty, first check the selected group, then review the update log. A webpage response, authentication failure, and parsing failure are different issues and should be handled separately. Import a manually shared link through the appropriate import option; do not assume it is a subscription URL based on its appearance.

  2. 02 / CONNECT

    Choose a server and traffic-capture method

    Select the configuration you want and set it as the active server, keeping a routing preset that suits your needs. On desktop, enable automatic system proxy configuration and test with a browser that uses system settings. On Android, approve the system connection prompt when starting, then check for the connection indicator in the status bar.

    The system proxy determines how apps send requests to a local endpoint; routing determines which outbound the core uses after receiving them. They are not interchangeable. Test a regular connection first, then consider TUN. Changing DNS, routing, and traffic capture all at once makes it hard to tell which change caused a failure.

  3. 03 / VERIFY

    Verify with a real request

    Open the target page and check the logs to see whether the request reached the client, the core started, and the remote server responded. A successful single connection test only confirms that test path; it does not prove that every app, domain, or transport will work. Keep a direct-connection test in your checks and confirm local network services remain accessible.

    If a connection fails, troubleshoot in this order: configuration parsing, core startup, DNS resolution, then connection establishment. Record the error type and what triggered it. Before sharing logs, remove subscription URLs and personal information. Before exiting the client, clear the system proxy so apps do not keep sending requests to a local port that is no longer open.

View the full guide →Connection troubleshooting and setup FAQ →

PROJECT V / CORE / CLIENT

Open-source ecosystem and client roles

V2Ray, V2Fly, Xray, and GUI clients are different components. Understanding what each one does makes it easier to choose the right setup and narrow down configuration issues than comparing software names alone.

CONCEPT

Project V

Modular proxy and routing design

CORE FAMILY

V2Fly / Xray

Configuration parsing, transport, and outbound handling

GRAPHICAL CLIENT

v2rayN / v2rayNG / v2flyNG

Subscriptions, interface, and system settings

Project V and the core families

Project V is a starting point for understanding V2Ray's technical background. Its modular design separates responsibilities such as inbound and outbound connections, transport, and routing. The V2Fly community continues V2Ray development and maintenance, while Xray has developed into a separate core line from related code. They share technical roots, but their feature development and supported fields are not identical. Even when the protocol name is the same, check the transport and security settings; that alone does not mean configurations are interchangeable.

The core establishes connections, while the GUI generates, saves, and organizes configurations. If startup fails, check the core parsing log first. Issues with subscription groups, interface preferences, or auto-start are more likely in the client layer. Keeping these layers distinct avoids repeatedly changing GUI settings while overlooking a protocol field the core does not support.

Three open-source GUI clients

v2rayN is for desktop systems, with tools for server lists, subscription groups, routing, and system proxy settings. v2rayNG is for Android and uses the Xray core; v2flyNG is another Android option, using the V2Fly core. All three have open-source project backgrounds, but they are separate programs, not different names for the same app. Check each client's setup options, system permissions, and feature support. Choose a platform first, then check protocol needs and core compatibility.

Open-source licenses set the terms for using, modifying, and distributing code; they do not guarantee compatibility with every environment. V2Fly's V2Ray and Xray-core follow different open-source licensing paths, and GUI clients and bundled components may have their own licenses. Personal use and redistribution are different cases. Before redistributing software, read the license files included with the relevant releases and retain any required copyright and license notices.

Check each update separately

The client, core, rule databases, and subscription are separate update targets. A client update may change the interface or how configurations are generated; a core update affects protocol support and connection behavior; GeoIP and GeoSite updates affect classification matches; and a subscription update refreshes server entries. Updating one does not update the others. If a rule stops working, check the tag in use, the rule database source, and where it is loaded—not just the subscription.

Keep your current working configuration and note any settings you change. Update one type of component at a time, then retest with the same request. If something goes wrong, it will be easier to roll back. For server parameter issues, check with your configuration provider; the client does not provide server access or automatically fix expired credentials. For more platform and installation details, read the complete cross-platform installation and setup guide.

NOTES / CONFIGURATION

Guides to clients and routing

Explore practical topics in order: learn where to find settings in the main window, understand how the cores differ, then maintain the rule databases used for routing. Configuration snippets must be used within the support limits of your client and core. After making changes, check the logs and test real requests.

View all articles →
Download clients