Client setup · subscriptions · traffic routing

V2Ray Beginner's Guide

Choose an open-source client for your platform, import a subscription, then configure traffic routing.

  • v2rayN
  • v2rayNG
  • v2flyNG

Import subscriptions
and route traffic

  • Import your configuration first, then route traffic
  • Configure system proxy and TUN separately
  • Illustrative interface; does not show live status

Client setup comes down to three questions: where the configuration comes from, how traffic enters the core, and which outbound route it takes. Subscriptions address the first; system proxy or TUN handles the second; routing rules and DNS together shape the third. Configure in that order to narrow down problems without jumping between settings pages.

The examples below show what each layer does using actual settings. This guide uses v2rayN for desktop and the corresponding features in v2rayNG or v2flyNG on mobile. Menu names and locations vary by client, and imported node details are not the same as a complete local setup. After moving from a computer to a phone, check per-app rules, DNS, and routing mode again.

v2rayN / Subscription Management
Subscription groupsAdd a group first, then enter the subscription URL
Group settings
Import subscriptionSubscription URLs and individual node links are handled differently
Update subscription
Active serverSelect one manually from the imported results
selected
Update methodFor the first import, check direct connectivity first
DirectVia proxy

Subscription management keeps node details updated in one place. Enter a URL from a trusted source in a subscription group, save it, and update the group. Then choose an active server from the results. Subscription URLs often contain access credentials, so keep them out of public screenshots, chat logs, and online conversion tools. Compared with pasting share links one at a time, group updates make it easier to keep nodes consistent across devices, but usually do not sync local routing, DNS, or per-app settings. If an update fails, first check whether the request can reach the URL, then see whether the URL has expired. Don’t delete all existing configurations as a first step.

Follow the steps to complete initial setup →

Four platforms
Choose an installer for your OS

  • Recommended for desktop: v2rayN
  • Recommended for mobile: v2rayNG
  • Check architecture and package format on the download page

When choosing an installer, confirm the operating system first, then the processor architecture, and finally the interface version or package format. The same subscription can be used across compatible clients, but installers are not interchangeable between platforms. When moving to a new device, don’t treat the entire application folder as a universal backup to overwrite. Handle node details, client preferences, and system integration settings separately.

Windows

Recommended: v2rayN

Download options include the v2rayN desktop edition and the classic WPF edition. The desktop edition uses a newer cross-platform interface, while WPF retains the familiar desktop experience. If you’re installing for the first time, start with the desktop edition. If you already have an established workflow, choose based on system requirements and your existing configuration—there’s no need to run both editions just because the interface differs.

After installation, import a subscription and select an active server before setting the system proxy. If you need TUN, check administrator permissions, the virtual network adapter, and whether other networking tools are using it. If your browser still can’t connect after you exit the client, first check whether the system proxy was restored instead of repeatedly reinstalling the application.

macOS

v2rayN

v2rayN offers installers for both Apple Silicon and Intel. Check your chip in About This Mac, then choose the matching architecture. After installation, launch the app from Applications and follow any required system permission prompts. If macOS displays a security warning, verify the file’s source and the warning details rather than disabling system security altogether.

System proxy settings may conflict with browser extensions, other proxy apps, or manual settings for the active network service. For your first test, use just one traffic-capture method. If behavior changes after switching Wi-Fi networks, check the proxy settings for that network service too. A connection indicator in the menu bar alone doesn’t confirm that every app is using the proxy.

Android

Recommended: v2rayNG

Start with v2rayNG using the Xray core; consider v2flyNG if you specifically need a v2fly core. Most recent phones are suited to the arm64 package. If you’re unsure of your device’s architecture, check the universal version notes on the download page. QR codes, share links, and subscription URLs serve different purposes, so identify which type of configuration your source provides before importing it.

The first time you connect, confirm the system VPN permission prompt. Per-app proxy settings determine which apps enter the client; routing rules then determine where their traffic goes. If the connection drops in the background, check battery optimization and the manufacturer’s background-app controls. To investigate high battery use, check actual traffic, reconnects, and app wake-ups rather than simply turning off notifications.

Linux

v2rayN

Choose a v2rayN deb or rpm package to match your distribution’s package manager, then select x64 or arm64. This desktop client requires a graphical session; it is not a background service. Before installing, check your desktop environment and runtime dependencies. After installation, launch the app from the application menu. Don’t mix packages for different architectures or formats when troubleshooting.

A desktop environment’s system proxy setting may not be honored by the terminal or every app. If a browser works but a particular tool doesn’t, check whether that tool supports proxies. TUN also requires permission to create a virtual network interface and adjust system routes. If you already use containers, virtual machines, or another VPN, watch for subnet and route-priority conflicts.

The installer only installs the client. To connect, you still need a valid node configuration or subscription and a traffic-capture method that suits your network.

Browse all clients →

Project V ecosystem
Where clients and cores differ

  • The graphical interface manages settings and system integration
  • The core handles protocols, resolution, and routing
  • Understand open-source licensing separately from node services
Configuration flow / rolesclient → core → outbound
Graphical clientsv2rayN · v2rayNG · v2flyNG
Subscriptions and local settings
Core familiesXray · V2Fly
Protocol and routing execution
Actual outboundRules select the outbound, not the client’s name
proxy / direct / block

From Project V to core families

Project V is an open-source ecosystem built around network proxy technology, with V2Ray among its best-known project names. As the ecosystem evolved, V2Fly continued community maintenance of related cores, while Xray developed independently on shared technical foundations. The projects have historical ties and share some protocols and configuration concepts, but their feature sets and specific fields do not always match.

A search for “V2Ray” often turns up protocols, cores, clients, and subscription services together. They are not the same thing. A client provides the interface, a core runs the configuration, a server provides the connection endpoint, and a subscription distributes node details in bulk. Knowing how these layers differ helps pinpoint whether an issue lies in the interface, configuration, system network, or server.

That’s why a recognized share link does not guarantee that every setting suits the current runtime environment. If a protocol or transport is incompatible, check the core’s capabilities against the server requirements rather than relying on the vague claim that it “supports V2Ray.”

Xray core and client selection

v2rayN is a graphical client for desktop platforms. It manages nodes, updates subscriptions, integrates with the system, and can call compatible cores based on its own support. v2rayNG is for Android and uses the Xray core; v2flyNG is an Android alternative for the v2fly core. Choose based first on platform and configuration requirements, then on your preferred workflow.

Core names are not a ranking of connection quality. Real-world performance also depends on server status, transport settings, the DNS resolution path, and your local network. If the same node behaves differently in two clients, compare the active node, routing mode, DNS, and traffic-capture scope first. Local setup differences can easily be mistaken for core performance differences.

To compare the three clients, start with the client comparison. If your configuration already works and there’s no specific compatibility issue, keep the current environment reproducible. A targeted migration is easier to verify than changing clients, cores, and rule sets all at once.

Open-source licenses and usage

All three clients are open-source software and can be used for free. The projects use open-source licenses; permitted use, modification, and redistribution are governed by each project’s license and the license texts for included components. The graphical client and core are separate software components, so one project’s license does not automatically apply to every component.

Open source describes the code and its licensing; it doesn’t choose a subscription service for you or mean every network endpoint is trustworthy. Keep subscription URLs, node credentials, and backup files secure. Before sharing logs, remove identifiable server addresses, user IDs, and access credentials. Keep only the error type and relevant settings needed to diagnose the issue.

This site focuses on download links and Chinese-language setup guides; it does not distribute nodes or host subscriptions. Whether a client connects successfully depends on a valid configuration, a compatible server, and local network conditions. Installation and network access are separate steps that need to be verified.

Update the client, core, and rules separately

Client, core, subscription, and rule-resource updates each affect different things. A client update may change menus, system integration, or how configurations are generated. A core update affects protocol and runtime behavior; a subscription update replaces node details; a rule-resource update changes classification and matching. Updating one does not mean the others have changed.

Before making changes, back up your current configuration and note the active node and routing mode. After updating, retest a scenario that worked before enabling new features. If something goes wrong, keep the logs and revert settings one at a time. That makes the cause easier to find than clearing subscriptions, reinstalling the client, and changing DNS all at once.

Menus and default behavior can change between releases, so these guides focus on what settings do and the order of operations. Choose an installer on the download page. For platform-specific preparation, permissions, and configuration checks, see the complete installation and setup guide for all platforms.

Initial setup: validation order

First, confirm that updating the subscription actually added selectable nodes, then choose an active server manually. Next, check that the core starts, and only then test the target app. If the browser works but other apps fail, check the traffic-capture scope. If the logs show a DNS resolution error, trace the DNS path. If no apps can connect, check for leftover system proxy settings, TUN routes, and local network issues. Change one variable at a time so you can compare results.

V2Ray node speed tests can help narrow down options, but they don’t replace testing real access. Test results depend on the request address, protocol, and timeout settings. One timeout doesn’t prove a node is permanently down, and one successful test doesn’t prove every app will work. Compare nodes under the same conditions, then test the services you actually need. Consider V2Ray subscription conversion only when the target client requires a different format. Conversion can omit fields or expose the full subscription URL, so it shouldn’t be the default fix for an import failure.

System proxy is not a routing mode, and TUN does not mean “proxy everything.” The former determines how traffic enters the client; rules still determine where it goes. V2Ray DNS settings also depend on how traffic is captured: app-level, system, and core-level resolution may follow different paths. Start with a minimal working setup, then add rules, sniffing, or FakeDNS as needed to reduce misdiagnoses caused by interacting features.

Start with subscriptions in the v2rayN setup guide →

Setup guides
and troubleshooting

  • Latest three technical articles
  • Understand how settings affect different use cases
  • Start with the beginner's guide for the basics

Once basic connectivity works, move on to syncing across devices, domain mapping, and DNS resolution paths. These topic guides explain when each feature is useful and what trade-offs it brings, so you don’t copy settings from one scenario to every device. Before reading, check your client, core, and traffic-capture method to relate the advice to your setup.