Client setup guides · Desktop and Android

V2Ray Config Guide v2rayN Download &Setup Guide

Download v2rayN View the guide

Choose a client for your platform, then configure subscription import, routing, and TUN mode.

Protocols VMessVLESSTrojanShadowsocks
Platform Windows Android macOS Linux

Settings / Common configuration

Five v2rayN settings entry points

The client manages configuration; the core establishes connections. Understand what subscriptions, the system proxy, and routing each control before changing settings. This helps prevent conflicting changes across multiple layers. The sections below follow common desktop menus. Android menu names may differ, but the workflow is the same: import a profile, select it, and start the service.

Subscription groups · Import and update

Save the group, then update the subscription

A subscription URL is not a single server profile; it lets the client retrieve a set of profiles. In v2rayN, open the subscription group settings, enter a group name and the URL provided by your provider, then save and update the subscription. After the update, check the selected group and make sure usable profiles appear in the list. Select one as the active server. Group updates are easier to maintain than entering each profile manually, but a failed update does not necessarily mean a node is down—the URL may have expired or the request may be unreachable. Subscription URLs may contain access credentials, so keep them out of screenshots, logs, and public discussions.

Subscription group → Subscription group settings → Add
Enter a name and subscription URL → Save
Subscription group → Update subscription (without proxy)
Select a group → Set as active server
View subscription import steps →

Downloads / Choose a package for your system

V2Ray clients by platform

For desktop devices, start with v2rayN; for Android, start with v2rayNG. Consider v2flyNG if your configuration requires V2Fly. The package must match both your operating system and processor architecture—a successful download does not guarantee it will run on your device. The download center lists installers, architecture details, and requirements. Version information is not fixed on the homepage.

Windows

v2rayN · Desktop / WPF

The desktop edition uses a cross-platform interface, while the WPF edition retains the classic desktop workflow. For a first install, start with the desktop edition; if you already have a preferred workflow, choose WPF as needed. Both require a valid profile to be imported—installing the app does not provide a server.

Before downloading, check your processor architecture and system requirements in Settings. On first launch, keep the default listening settings; avoid changing the port, core, and routing all at once before establishing a connection. If you need TUN, check the required permissions separately.

Go to downloads

macOS

v2rayN · Apple Silicon / Intel

Open “About This Mac” and check the chip or processor information first. Choose the matching architecture for Apple Silicon or the Intel option for an Intel Mac; don't rely on the device's appearance or purchase year. The download center lists both installers side by side so you can choose based on your device.

On first launch, watch for prompts about app and network permissions. First confirm the client starts and can import a subscription, then configure the system proxy. If another network tool is routing traffic, pause one of them to reduce conflicts between routing and DNS settings.

Go to downloads

Android

v2rayNG recommended · v2flyNG alternative

v2rayNG uses the Xray core, while v2flyNG uses the V2Fly core. Choose a client based on your configuration requirements, then select the arm64 or universal package. Most recent devices use arm64; if you're unsure about the architecture, check your device information and use the universal package if needed.

Confirm the system VPN permission when starting the service. If the connection drops frequently after the screen locks, check battery optimization and background activity restrictions. When comparing the two clients, stop the existing connection first to avoid mistaking Android's single-active-VPN limitation for a configuration problem.

Go to downloads

Linux

v2rayN · deb / rpm

Choose deb or rpm to match your distribution's package system, then check whether your device uses x64 or arm64. The download center provides packages for both architectures. When possible, open the package with your distribution's graphical installer, and note the exact name of any dependency reported as missing.

After installation, check whether the target app follows your desktop environment's proxy settings. App support for system proxies varies. If a browser works but another app does not, first check how its traffic enters the client. TUN requires additional permissions, so avoid configuring it at the same time as your first subscription import.

Go to downloads

View all clients →

Quick start / Establish a basic working connection

From subscription import to access check

Change one type of setting at a time. First confirm the profile connects, then refine routing and traffic capture. If something goes wrong, you can identify which step introduced the change. These steps focus on the v2rayN desktop client; on Android, follow the equivalent workflow in v2rayNG: import a profile, select it, and start the service.

Step 01 / Profile source

Import a subscription and select a server

Get the subscription URL or individual share link from your configuration provider. Enter a subscription URL under “Subscription group settings”; for a share link, use the import-from-clipboard option. Don't enter both types in the same field. Save the group, update it, check the returned list, and set one profile as the active server. On Android, use the corresponding add-profile or subscription settings option.

If the update returns no profiles, first switch to the right group and check that the URL is complete, has no extra spaces, and hasn't been changed by your provider. A subscription page opening in a browser does not guarantee that it returns a format the client can use. Don't keep repeating the update and overwrite useful information; note the error shown by the client first.

Detailed subscription import steps →

Step 02 / Traffic entry

Configure the proxy and basic routing

On desktop, start by selecting “Set system proxy automatically” and choosing a suitable routing preset. The system proxy determines whether apps that support it send requests to the local listening port; the routing preset determines where connections handled by the core go. These settings serve different purposes, and there's no need to write complex rules for your first connection.

If the target app has its own proxy settings, confirm that its proxy type, address, and port match the client. Leave TUN off for now and use a browser to verify the basic connection. On Android, approve the system prompt when starting the service, then check whether per-app proxying is enabled. Apps excluded from the proxy won't follow this connection path.

Routing and mode settings →

Step 03 / Connection check

Test access, then check the logs

After starting the service, test one address expected to connect directly and another expected to use the proxy. A change to the client icon alone doesn't prove that requests are going through the proxy; check the results alongside the connection logs. A node latency test is not a download speed test, and a single result is not a reliable measure of stability.

If access fails, check in this order: did the core start, is the local port listening, is the app using the proxy, and is the remote server reachable? Note the error keywords before making changes, and don't reinstall everything at once. Before sharing troubleshooting details, hide subscription URLs, server credentials, and personal network information. Include only the steps taken, error type, and relevant environment details.

Diagnose by symptom →
View the full guide →

Open-source ecosystem / Clients and cores

Project V, V2Fly, and Xray

V2Ray is often used as a broad label for a family of proxy tools, but an actual setup involves four separate layers: graphical client, proxy core, protocol, and server. When downloading, check the client name; for configuration compatibility, check the core and protocol; and when troubleshooting network issues, follow the actual connection path. Similar names don't mean every setting is interchangeable.

Configuration layers

Interface management
Core handles connections

  1. Graphical clientManages subscriptions, configuration, and startup options
  2. Proxy coreParses rules and establishes the actual connection
  3. Protocol and transportDefine how communication works and which parameters are required
  4. Remote serverProvides a connection endpoint matching the configuration

View the glossary →

Project V is the ecosystem, not a single download

Project V is a modular proxy ecosystem, with V2Ray as one of its widely used core projects. The V2Fly community continues to maintain V2Ray-related implementations, while Xray developed from a V2Ray fork and has its own feature development and parameter support. Understanding this relationship helps make sense of core options in a client: they share a history, but configuration fields, protocol extensions, and routing behavior are not necessarily identical.

Most users don't need to edit a complete core configuration directly. The graphical client generates a runtime configuration from subscription profiles and interface settings, then starts the appropriate core. Manual changes to generated files may be overwritten the next time you switch servers or save settings. For changes you need to keep, use the client's settings wherever possible and note the behavior before and after.

Open-source licenses and use cases of three clients

v2rayN, v2rayNG, and v2flyNG are community-maintained, open-source graphical clients that are free to use. v2rayN is released under GPL-3.0 for desktop configuration management; v2rayNG also uses GPL-3.0, targets Android, and uses the Xray core; v2flyNG uses GPL-3.0, targets Android, and uses the V2Fly core. A software license governs the use and distribution of code; it does not mean the client includes a remote service you can connect to.

For desktop, start with v2rayN; for Android, consider v2rayNG first. If your configuration specifically requires V2Fly behavior, evaluate v2flyNG. The three clients differ in interface, core, and platform permissions, so when switching, review routing, DNS, and which apps use the proxy—not just whether the server profile imported. See the client comparison for details.

Check core licenses and protocol support separately

The core code for V2Fly and Xray is generally licensed under MPL-2.0, a different licensing layer from that of the graphical clients. Open source means you can view, modify, and distribute the relevant code under the license terms. To determine whether a configuration will work, check which protocols and transport fields the specific core supports. VMess, VLESS, Trojan, and Shadowsocks are protocol names, not server addresses, and the protocol alone doesn't indicate speed.

For example, a configuration with specific TLS or REALITY parameters must match the server's settings and use an implementation that supports those fields. Don't disable certificate verification just to get rid of an error. First check that the system time is correct, the domain matches, and all required parameters are present; then decide whether to update the client or switch cores. If a parameter is unclear, look it up in the glossary before experimenting with settings—it's easier to reproduce and troubleshoot.

Handle software updates and subscription updates separately

Client updates affect the interface, dependencies, and configuration generation; core updates affect protocol implementations and runtime behavior; subscription updates only refresh server profiles. A successful subscription refresh doesn't mean the software is up to date, and installing a newer client won't automatically fix an expired subscription. The download center provides client installers; check with your configuration provider for subscription URLs and service status.

Before updating, back up your current settings and note the active core, listening port, and custom rules. After the update, verify the basic connection before restoring extra settings one at a time. If the new setup fails, keep the first error in the logs and the steps that triggered it—not just the last “startup failed” line. For connection timeouts, DNS resolution problems, or lingering system proxy settings, go to Troubleshooting. For general questions, start with the FAQ before reinstalling anything.

Guides / Configuration and troubleshooting notes

Choosing a Client and runtime logs

Once the basic connection works, explore these guides for specific issues. The client comparison explains platform and core differences; the log guide uses error keywords to track down problems; and the startup failure guide separates port conflicts, invalid formats, and unsupported fields. First identify which layer is involved, then decide what to change.

Troubleshooting

Xray core fails to start: Troubleshoot port conflicts, JSON syntax, and configuration errors

If the core exits as soon as it starts, check for port conflicts, configuration file format issues, misspelled fields, and core version compatibility. Pinpoint the line causing the error. First distinguish a configuration parsing failure from a connection failure, then decide whether to change settings or investigate the network.

Read the startup troubleshooting guide →

View all articles →