• Open-source clients
  • Xray · V2Fly
  • Setup notes

V2Ray Setup Guide

Start by importing a subscription, then understand the difference between system proxy and routing. Use v2rayN on desktop; choose an Android client based on core requirements.

Client settings, feature by feature

Import your configuration first, then choose which apps to route through the client and which connections should go direct. Change one layer at a time to make results easier to verify.

SUBSCRIPTION

Subscription group settings

A subscription URL retrieves configurations in bulk; it is not a browser proxy address. In v2rayN, open Subscription Group Settings, add a group, enter a recognizable alias, paste the full URL and save. Then update the subscription. Groups are easier to keep in sync with server-side changes than manually entered configurations, but updates may overwrite manual edits. In v2rayNG, use Subscription Group Settings from the menu to do the same. If the list is still empty after updating, check for extra spaces or an expired URL, then review the request errors in the log. Avoid repeatedly deleting all your configurations.

See how to import a subscription →
Subscription group settings
Alias: Daily setup / Updates: On

V2Ray client downloads

Check your operating system first, then your processor architecture. v2rayN is the main desktop option; on Android, choose a client based on whether your configuration requires Xray or V2Fly. The download center lists package types and system requirements.

Windows

Use v2rayN to manage subscription groups, system proxy and routing rules. The download page offers a desktop edition and the classic WPF edition. The desktop edition uses a newer cross-platform interface, while WPF retains the classic desktop UI. Menu locations may differ slightly between the guides and the app, but the configuration goals are the same.

Check system and architecture requirements before installing. On first launch, import your configuration and test browser access before deciding whether to enable TUN. Insufficient permissions and an expired subscription URL are different issues. If the computer already has a configuration, export a backup before switching client editions.

Download

macOS

Before choosing v2rayN, check your chip in “About This Mac.” Apple Silicon and Intel require different installer architectures, so don't rely on the computer's appearance or purchase year. The download center lists separate options for each. After installing, check that macOS allows the required network access and app permissions.

You may be able to reuse a compatible subscription URL from the same provider, but don't overwrite desktop settings files on another platform. If a browser and other apps behave differently, first check whether those apps use the system proxy. To route more traffic, consult the handbook for TUN support and permission requirements.

Download

Android

Start with v2rayNG; consider v2flyNG when using a V2Fly configuration. Both offer arm64 and universal builds. If you're unsure of your device's architecture, check its system information. The universal build is for broader architecture compatibility. Similar client names don't guarantee identical support for protocol extensions.

On first connection, the system will ask for VPN permission. Make sure the request comes from the client you just installed. Once connected, check app routing and background battery restrictions. If the connection often drops when the screen is locked, check the system's background policies before rebuilding all your subscriptions. Verify the source before importing a QR code, too.

Download

Linux

v2rayN offers packages for different Linux distributions. First choose deb or rpm, then x64 or arm64. The distribution determines the package format; the device determines the processor architecture. Both must match. Once the GUI opens, configure proxy access and system proxy settings for your desktop environment.

Desktop environments, browsers and terminal apps may handle proxy settings differently. A working browser does not mean every app is using the proxy. To troubleshoot, start with one app as a baseline and identify where it gets its proxy settings. If using a virtual network interface, check permissions and how it interacts with existing network services separately.

Download

From subscription to connection in three steps

First establish a connection you can verify, then add routing rules and expand traffic coverage. These steps focus on desktop v2rayN; Android v2rayNG follows the same import process but uses a different connection authorization flow.

  1. Add a group and update the subscription

    Install and open the client, then add an entry under Subscription Group Settings. Use the alias to identify the configuration source, paste the full subscription URL provided by your service, save and update. Once configurations appear, select one and set it as the active server. Copying the URL to your clipboard alone does not import it.

    If you have a single share link, use the appropriate import-from-clipboard option rather than treating it as a subscription URL. A QR code may also contain just one configuration. These formats are updated differently: subscriptions can be fetched again, while a single configuration usually needs to be shared again. Subscription URLs grant access, so cover the full URL before taking screenshots and don't submit it to unfamiliar online conversion tools.

  2. Select a configuration and enable a connection method

    On desktop, select an active configuration, enable automatic system proxy configuration and start with an easy-to-understand routing preset. On Android, select a configuration, start the connection and read and approve the system VPN permission prompt. A button changing state only shows that the client tried to start. Check the logs for configuration parsing errors, port conflicts or permission issues.

    System proxy and routing are separate settings layers. “Set system proxy automatically” does not mean “route all connections through the proxy.” The first controls how apps connect; the second determines the outbound path after they connect. If another proxy tool or network accelerator is running, pause one before testing to prevent multiple programs from repeatedly changing the same system settings.

  3. Test access, then add rules

    Use a browser known to follow system proxy settings to visit a known site, then check that local network services that should connect directly are still accessible. If an error occurs, note when it happened, which connection method you were using and what the logs say. Distinguish subscription update failures, connection failures and DNS resolution failures; each requires a different troubleshooting path.

    Once the basic connection works, adjust routing, app-level routing or TUN. Change one thing at a time and test immediately, keeping a configuration you can restore. Before ending a desktop session, check whether the system proxy has been cleared. For long-term use, periodically check subscription updates, background permissions and logs. Keeping these notes is more useful for diagnosing issues than repeatedly switching clients.

View the complete setup guide

Project V, cores and clients

Keep the roles distinct: the ecosystem provides the technical background, cores handle connections, and GUI clients organize everyday settings. Choose based on compatibility, not assumptions based on names.

PROJECT / BACKGROUND

Project V is an ecosystem, not a single installer

V2Ray originated in the Project V ecosystem, which has evolved around proxy protocols, transport methods and routing capabilities. In everyday searches, “V2Ray client” often means a GUI app using related technology, not one specific desktop application. Understanding the distinction helps you tell client names on download pages apart from protocol names in configuration files and core names in logs.

V2Fly continues community development of projects related to V2Ray, while Xray is another core that developed from the same roots. They share some technical background, but their features, parameters and extension support don't always match. If the same subscription behaves differently across clients, the cause may be the import format, core capabilities or how the client generates its configuration—not necessarily an invalid URL.

This site separates downloads from setup guides: the download center helps you choose a platform and installer, tutorials explain the interface, and the complete handbook covers concepts and troubleshooting. This site provides setup guidance, not proxy services or subscription accounts. To test a connection after installing a client, you'll still need a compatible configuration that you're authorized to use.

CORE / COMPATIBILITY

V2Ray core comparison: start with protocol support

The core handles protocols, connection setup, DNS and routing; the GUI turns your input into a core configuration. To assess compatibility, check the protocol, transport and security settings together. “Supports VLESS” does not mean every VLESS combination is supported. If a setting is missing, first check whether the current client and selected core support it.

v2rayN's multi-core management makes it easier to work with different configurations on desktop, but switching cores doesn't automatically convert every parameter. On Android, choose v2rayNG or v2flyNG according to the configuration requirements from your service provider. There's no need to switch a working setup just because the name is different. Test a different core for a specific capability, and keep the working option as a fallback.

If startup fails, check the log entry closest to the failure time. Determine whether it points to an unsupported field, a configuration parsing error or a remote connection failure. The first two are more likely to be local compatibility issues; the last may involve the network path or service status. Classify the error before switching cores so you can tell whether the change helped.

Read more about cores and the ecosystem →
PROTOCOL / TRANSPORT / SECURITY

Understand protocols, transports and REALITY separately

VMess, VLESS and Trojan are common protocol names in configurations, each with its own transport and security parameters. REALITY is a related security mechanism; it cannot replace the server address, port or user ID. If an imported configuration appears in the interface but fails to connect, check whether its transport and security parameters were recognized correctly instead of changing only its display name.

Subscription conversion adapts formats; it doesn't add capabilities a core lacks. Some extension fields may be lost during conversion, so prefer subscriptions from a clear source that directly support your client. If conversion is necessary, check how the tool handles data and where sensitive information goes. Avoid giving a complete access-bearing URL to an unfamiliar third-party site.

For initial setup, use a share link or QR code the client can recognize directly to reduce manual entry errors. If you need to edit settings by hand, compare each field with your provider's instructions, especially the domain, security layer and transport path. More toggles do not make a client setup better; they only help when they match the server settings.

See protocol and parameter details →
MAINTENANCE / RECOVERY

Maintenance order: updates, backups and TUN

Open source means the code can be inspected, used and modified under the terms of its project license. It does not mean every derivative build has the same features. All three clients come from the open-source ecosystem; when discussing free use, distribution or modification, consider the separate licenses for each client, core and related component. Proxy service terms are set separately by the provider.

Before updating, note your platform, client edition and selected core, and export any configuration you need. Subscription updates sync server configurations; client updates change the interface or features; rule data updates are a separate maintenance task. Don't treat these as the same action. Subscription sync is not a substitute for a local backup: routing, custom DNS and interface preferences may not be included in the subscription.

TUN affects how system network traffic is routed, so enable it only after verifying a basic connection. Beforehand, learn how to turn it off, restore the original system proxy and check for other virtual network interfaces. If something goes wrong, exit TUN and test the regular proxy. If that works, focus troubleshooting on traffic capture, routing or DNS instead of reinstalling the entire client.

Read about TUN and routine maintenance →

Tips and troubleshooting notes

Go beyond basic connectivity with notes on local network sharing, DNS query paths and syncing across devices. Each article focuses on one setup issue: check the requirements first, then change the configuration.