Client and Core Reference

V2Ray ZenClients & Protocols

Choose an open-source client for your operating system, start by importing a subscription, then check the protocol guide for core and transport compatibility.

  • VMess
  • VLESS
  • Trojan
  • Shadowsocks
  • REALITY

Protocol lineage: V2Fly and Xray both implement VMess, VLESS, Trojan, and Shadowsocks. Of the two cores shown, only Xray implements REALITY.

01 Configuration Guide

Client Configuration Essentials

The core handles connections, subscriptions organize entries, and routing selects the outbound path. The connection method determines which app traffic enters the client.

The client manages imports, groups, and runtime status; the core parses the configuration, establishes connections, and applies routing. After importing, check the protocol, transport, and connection security settings, then confirm which core the client uses for that entry. Of the V2Fly and Xray cores, entries using REALITY require Xray. Desktop v2rayN can use different cores depending on the configuration, while one key difference between v2rayNG and v2flyNG is their default core. If fields are incompatible, check the core and configuration format first rather than switching to a client with a similar-looking interface.

Platform
Desktop and Mobile
Core
V2Fly / Xray

02 Platform Guide

Find an Installer by OS

Your OS determines where to find the installer; your CPU architecture determines which file to download. When moving to a new device, check its system information before choosing a package.

Windows

On desktop, v2rayN is available as a cross-platform edition and a classic WPF edition. Their interfaces and menu locations differ, so check which version a guide uses before following its screenshots.

When migrating from an older installation, first identify the configuration directory and startup method. On the first run of the new version, check your subscription groups and local listening port; don’t enable launch at startup just yet. If the old client is still running in the background, quit it before testing to prevent the two processes from competing for a port or overwriting system proxy settings.

macOS

v2rayN has separate installers for each chip. Open About This Mac to check the processor: choose arm64 for Apple Silicon or x64 for Intel. Don’t guess the architecture from the computer’s appearance or purchase year.

If the app opens but can’t establish a connection, check whether the OS is blocking it from launching, whether the core is running, and whether the network service is reading the proxy settings. These issues can look similar. If a security alert appears, verify the app’s source and system requirements; don’t change global security settings to troubleshoot.

Android

v2rayNG uses Xray by default; if your configuration is based on V2Fly, compare it with v2flyNG. Both clients offer arm64 and universal installers; choose the one that matches your device’s supported architecture.

If the OS asks for permission when you start a connection, first confirm that the request came from the client you’re testing. If another VPN connection is active, check whether the new connection will replace it. Updating an app is not the same as switching to another client; switching usually means importing your subscription again and checking your routing settings.

Linux

v2rayN offers deb and rpm packages for x64 and arm64. First check which package format your distribution uses, then confirm your hardware architecture. Package format and CPU architecture are separate requirements.

If the client starts after installation but apps don’t use the system proxy, check your desktop environment and the proxy settings in the affected apps. An app may use its own network configuration, and command-line programs may not read the desktop’s settings. Confirm the client’s local port is available, then check whether each app is using it. This helps avoid mistaking a desktop integration issue for a remote connection problem.

Browse all clients →

03 Getting Started

Import, Connect, and Test

For your first setup, choose one connection with a known purpose. Confirm each step works on its own before enabling automatic updates or changing routing rules.

  1. Import and Check an Entry

    Get a share link from a trusted source, or paste a subscription URL into the appropriate subscription field. In desktop v2rayN, you’ll usually create a group and then update it; in v2rayNG, add a source in subscription management and update it. After importing, check the protocol, transport, and connection security fields against the provider’s instructions. Don’t rely on the entry name alone.

    If the list is still empty, check whether you pasted a subscription URL into the single-entry import field, or a single share link into the subscription field. If entries appear but fail to start, note the error type and check whether the core supports them. Repeatedly refreshing the subscription won’t fix incompatible configuration fields.

  2. Choose a Connection Method

    Select an entry and start the client. On desktop, first test with an app that reads the system proxy. On mobile, confirm connection permissions when prompted by the OS. The connection method and outbound mode are different settings: the former determines whether app traffic enters the client; the latter determines which outbound path it takes once inside.

    If only one app keeps using its original connection, check whether it has a separate proxy setting before changing servers or rewriting rules. If you need TUN, note your current settings first, then check that local network access and DNS resolution still work as expected. Change one setting at a time to make differences easier to pinpoint.

  3. Test the Connection and Restore Settings

    Open a specific test destination, check the client logs for a matching connection, and confirm the target app can complete a real request. Seeing the core running only means its process has started; a successful latency test doesn’t mean every app is using the connection. If there are no requests in the logs, check local settings first. If requests appear but the handshake fails, check the remote parameters.

    After testing, quit the client and retry the original network path to confirm that apps aren’t still sending requests to a closed local port. Once you’ve confirmed that the connection starts and the original setup is restored, consider enabling launch at startup. Record the client, core, and connection method that worked so you can reproduce the setup after an update or migration.

Read the full guide →

04 Open-Source Lineage

Project V and the Two Cores

Using the same protocol name doesn’t guarantee that configurations are interchangeable. Check the client, core, transport, and subscription format separately when choosing a setup.

V2Fly
Continued development of the V2Ray core
Xray
Forked from V2Ray code
REALITY
Implemented by Xray only

Read the Protocol Guide

From Project V to Community Maintenance

Project V provides a set of tools for building network proxies. Within this ecosystem, V2Ray handles connections, separating traffic ingress, protocol handling, and routing. This division continues in today’s graphical clients: editing an entry in the interface changes the fields the core uses to establish a connection; changing a route determines where traffic goes after entering the core.

V2Fly continues community maintenance of the V2Ray core. The project’s history explains why tutorials and menus often use similar names, but it doesn’t tell you what a feature does. When reading documentation, first work out whether V2Ray refers to the ecosystem, a specific core, or a client category. If a guide only says “open V2Ray,” check the interface name and configuration to determine which layer it applies to.

Shared Protocols and Core Differences

Xray was forked from V2Ray code. Like V2Fly, it implements VMess, VLESS, Trojan, and Shadowsocks, but shared protocol names only mean both cores support that type of connection. The two ends must also agree on the transport, connection security settings, and implementation-specific parameters. REALITY is a connection security mechanism often paired with VLESS; of the two cores shown, it is implemented by Xray. When migrating, check the relevant entry fields first rather than assuming compatibility just because both support VLESS.

Try migrating one known-working configuration first, then handle subscription groups and routing. Recognizing a share link, starting the core, and establishing a connection are three separate checkpoints. If the first fails, check the format; if the second fails, read the core logs; only the third calls for investigating remote settings and the local network. This makes it easier to find the problem than copying everything over and guessing at each setting.

Open-Source Clients and Independently Maintained Cores

v2rayN, v2rayNG, and v2flyNG are all open-source clients, with their interface code and cores maintained separately. v2rayN focuses on desktop server management and system integration; v2rayNG primarily uses Xray; v2flyNG is for mobile configurations using V2Fly. The graphical interface turns settings into data the core can use, so importing the same entry into different clients may show different names and default values.

Open-source licensing and protocol compatibility are separate concepts. A license explains how a project’s code may be used, modified, and redistributed; a protocol specification describes how the two ends of a connection exchange data. When reviewing a project, check the client and core licenses separately. When comparing clients, focus on whether they can represent every field your existing configuration requires, not just how many protocols appear in the menu.

Update the Interface, Core, and Rule Data

Client updates can change subscription screens, import behavior, and system integration. Core updates can change supported fields, default behavior, or error messages. Rule data updates can change how a destination is matched. These updates may be released separately, so if behavior changes, first check which layer was just updated. If there was already an issue before updating, keep the original error details so you don’t mistake an old problem for a regression.

Record key settings before updating, back up subscription groups and custom rules as needed, and store backups containing credentials securely. After updating, retest the same destination in order: can the client start, can it import the entry, can it connect, and does routing match? If only one part is affected, start by checking that layer. It’s easier to find the cause than by reinstalling the client and rewriting the subscription at the same time.

Choose Based on Compatibility

If you already have a server configuration, start client selection with the remote parameters: check the protocol and transport, then confirm core support, import format, and the local connection method. A subscription is a way to deliver entries, not a connection protocol. Whether different clients can open the same subscription URL depends on whether they can parse its response; even after parsing succeeds, check the connection requirements for each entry.

When comparing speed or battery use on mobile, don’t rank clients by protocol name alone. Routes, transport, reconnect frequency, and background behavior all affect results. Test the same tasks on the same device and under similar network conditions, comparing the initial handshake, sustained traffic, and idle keepalives separately. If you’re only changing devices, keep the existing connection parameters and change only how the client represents them. For other configuration issues, see Troubleshooting.

05 Article Index

Connection Testing and Server Management

These three guides explain what test results mean, the limits of LAN access, and the factors to consider when choosing a server.

Browse all articles →

V2Ray Client Downloads