Client Setup · Protocol and Core Reference

V2Ray Knowledge BaseClient Downloads and Setup

Choose an open-source client for your platform, start by importing a subscription, then learn about routing and proxy settings.

Graphical interface Xray · V2Fly Subscriptions / Routing / TUN
Subscription Groups →

Save URLs by source and update each configuration separately.

Routing →

Choose an outbound based on the destination domain and IP.

System Proxy and TUN →

Understand the difference between app-level proxying and routing traffic through a virtual network adapter.

These static illustrations do not change device settings. Menu names may vary between client versions. The outbound tags in the routing example must exist in your configuration.

Explore setup guides by setting

First check whether traffic reaches the client, then inspect matching rules and the remote connection. Subscriptions, routing, and system proxy settings solve different problems; there’s no need to change everything at once.

The client provides the interface; the core handles connections and routing. Importing a subscription only saves server settings—it does not automatically route every app through the proxy. For your first setup, keep the default routing, select an existing configuration, and test browser access through the system proxy. Then configure other apps as needed. This makes it easier to tell subscription issues from proxy entry-point or protocol problems.

A subscription fetches server settings in bulk; it does not replace routing or proxy entry-point settings. In v2rayN, open “Subscription Group” → “Subscription Group Settings,” add a remark, and paste the full URL. Save it, then update the subscription. Create a separate group for each source to make updates easier to check and entries easier to remove. If an update fails, check the log first, then confirm the link has not expired and whether it needs a proxy connection. Subscription URLs often contain credentials, so hide them before sharing screenshots. Locally edited entries may also be overwritten during the next update.

See how to import a subscription →

Find the right download for your platform

Use v2rayN on desktop. On Android, start with v2rayNG; consider v2flyNG if you need a V2Fly core. Check your operating system and processor architecture first, then choose the right edition.

Windows

v2rayN is available as a desktop edition and a classic WPF edition. The desktop edition uses a cross-platform interface, while WPF retains the native Windows interface framework. If you already have a preferred edition, you can stick with it—there’s no need to rebuild all your settings just because the name is different.

Before downloading, check your system type under “Settings” → “System” → “About” or “System Information.” Back up your existing configuration before installing or migrating, and avoid mixing old and new program directories. On first launch, import a subscription and select a server before setting up the system proxy. Check TUN permissions separately from the permissions needed to launch the regular interface.

Go to downloads

macOS

The v2rayN desktop edition has separate downloads for Apple Silicon and Intel. Open “About This Mac” from the Apple menu and check “Chip” or “Processor” to choose the right package. Don’t rely on the computer’s appearance or purchase year.

After installation, move the app to a convenient applications folder before launching it. Review any system security warnings in light of the download source and the warning details. If a browser works but other apps don’t, first check whether those apps follow the system proxy. Before enabling TUN, make sure authorization is complete and check whether other network tools are already routing traffic.

Go to downloads

Android

v2rayNG uses the Xray core and is our recommended Android client; v2flyNG is an alternative for the V2Fly core. Most recent devices can use the arm64 package. If you’re unsure of your device architecture, check its specifications and compare them with the universal package details on the download page.

Import a subscription or share link in the client, select a configuration, and start the connection. Approve Android’s VPN connection request when prompted. Android’s local VPN interface routes app traffic into the client; that is separate from whether the remote server is reachable. If the connection drops in the background, check the logs as well as battery optimization, background-running permissions, and whether another VPN app is in use.

Go to downloads

Linux

The v2rayN desktop edition offers deb and rpm packages for x64 and arm64. Check your distribution’s package format and processor architecture, then open the right file with your system’s package installer. This helps avoid mistaking a package-format mismatch for a program fault.

Desktop environments vary in how they handle system proxy settings. After importing a configuration, test the local listening address and port in an app that supports manual proxy settings. If you plan to use TUN, check permissions and routing separately; don’t run the entire desktop session with elevated privileges. If the connection fails, check both the client logs and system network settings to narrow down the cause.

Go to downloads

Common setup questions

Subscription imported successfully, but why can’t my browser access the internet?

First confirm that a server is selected and the core is running, then check whether the system proxy points to the current client. Seeing entries in the server list only means the configuration was loaded. A browser extension with its own proxy settings may override the system settings. Check in this order: core logs → system proxy → browser settings. There’s no need to keep deleting and reimporting the subscription. Browse setup and troubleshooting FAQs →

Should I choose REALITY or VLESS?

They aren’t alternatives at the same layer. VLESS is a proxy protocol; REALITY is a security mechanism used in certain connections, and they can be used together. Whether a connection works also depends on the transport, server settings, and core support. Keep the combination provided when you import the configuration rather than swapping components based on their names. Read about REALITY →

Should I enable TUN right away?

TUN doesn’t have to be your first step. If the app you want to use follows system proxy settings, test that first. If it ignores them and you need to route its traffic, check TUN permissions, DNS, and routing. Android clients use the system VPN interface, which works differently from a desktop system proxy; follow the guide for your platform. See system proxy and TUN setup →

Project V and the core ecosystem

Look at the project ecosystem, runtime core, and graphical client separately. Similar names don’t guarantee identical configuration fields, release schedules, or feature sets.

Projects and technology

Project V

V2Ray originated in the Project V ecosystem, where inbound and outbound connections, routing, and transports are organized as configurable components. Understanding this structure makes it easier to adapt settings than simply memorizing where a button is in one client.

Community-maintained fork

V2Fly

V2Fly continues the community-led development of the V2Ray core project, evolving its supported configuration formats and transport capabilities. v2flyNG provides an Android interface for configurations that specifically need this core ecosystem.

Independently developed core

Xray

Xray originated from V2Ray and is now maintained independently. Check support for configurations such as VLESS and REALITY against the specific core you use. v2rayNG brings related Xray capabilities to an Android graphical client.

What clients and cores do

v2rayN, v2rayNG, and v2flyNG are all open-source graphical clients, but they aren’t simply the same program with different names for different operating systems. Clients manage subscriptions, display servers, save interface settings, and prepare configurations for the core. The core then uses those configurations to establish connections, handle transports, and apply routing. So a client opening normally doesn’t mean the core started successfully, and a subscription updating successfully doesn’t mean its server settings are suitable for the current core.

v2rayN is designed for desktop systems and can manage configurations for different cores; available features depend on what’s installed and shown in the interface. v2rayNG and v2flyNG provide Android interfaces built around the Xray and V2Fly ecosystems respectively. When migrating, transfer standard share links or subscriptions first, then review device-specific settings. System proxy ports, TUN permissions, per-app routing lists, and file paths usually can’t be copied directly from another device.

Open-source licenses and configuration privacy

Open source means the program’s source code is available under its applicable license for review, use, and contributions subject to that license. The v2rayN, v2rayNG, and v2flyNG client projects use GPL-family licenses; the V2Fly and Xray core projects use MPL 2.0. Clients, cores, and their dependencies are separate licensing matters. When distributing or modifying software, read the licenses provided with each component rather than relying on the name of just one project.

Open-source status doesn’t remove the need to evaluate remote services and configuration sources. Subscription URLs may contain account identifiers, and share links may include authentication details. Before asking for help, hide full URLs, user IDs, passwords, and key fields; share only the error and the relevant setting names. Don’t paste real configurations into unfamiliar websites to convert formats. Our glossary explains parameter meanings without requiring you to submit personal configuration data.

Update clients, cores, and rule sets separately

Updating the interface, updating the runtime core, and updating GeoIP or GeoSite are separate operations. A client update may change menus or subscription parsing; a core update may add field support or change validation; a rule-set update changes category matches. If something breaks, note which layer changed. Updating everything at once makes it difficult to identify the cause.

Back up working configurations before updating, and note the routing profile and proxy entry point you use. After updating, test a configuration that worked before before trying new settings. If the log reports a missing category, check the rule set; if it reports an unknown field, check core compatibility; if only one app has a problem, check that app’s proxy settings. This process can save you from reinstalling components unrelated to the issue.

Connection checks versus speed test results

TCPing, real-connection latency tests, and download speed tests measure different stages. A successful TCP connection to a port doesn’t prove that the proxy handshake, DNS resolution, and destination website are all working. Real-connection tests are also affected by the test endpoint, routing, and DNS. Download tests depend more on transfer duration, the destination service, and current network conditions. Before comparing results, make sure you’re using the same test method under the same conditions.

For a first setup, test access to a specific destination, then check where the logs show an error. A test that returns no value doesn’t prove every configuration is broken, and a successful port test doesn’t explain why an app can’t connect. If you’re unsure what a test measures, read the speed-testing guide before changing servers, DNS, or routing rules.

Configuration Guides and How-Tos

Explore specific questions: how to interpret test results, choose a desktop edition, and migrate configurations across devices. Check each procedure against the settings in your current client.