PLATFORM / 01
Windows
Choose v2rayN. The desktop edition uses a cross-platform interface, while the classic WPF edition retains the traditional workflow. Pick the one that matches your preference.
V2Ray Client Configuration Checklist
V2Ray Starter Guide
Choose a client for your operating system, then work through each setting. The guide covers subscription import, system proxy, and connectivity checks, with the exact setting location and verification criteria for every step.
Free forever
Open source
Chinese documentation
Xray · V2Fly
Client selection
Confirm the app type for desktop platforms
v2rayN
Confirmed
In progress
Subscription import
Paste the complete link, then update manually
vmess://your-subscription
System proxy
Enable proxy takeover after connecting
ON
Connectivity check
Check logs, system status, and the target app
Check
04 supported platforms
03 graphical clients
CORE Xray · V2Fly
PROTO VMess · VLESS · Trojan
Enablement checklist
Four key checks for V2Ray client setup
Choose the client first, then handle the subscription, system proxy, and connection status. Select a check on the left to see its scope and verification criteria on the right.
Check 01
Choose the client for your system before starting; do not mix installation instructions
For desktop use on Windows, macOS, and Linux, v2rayN is the primary path; on Android, start with v2rayNG. If you need the V2Fly core, consider v2flyNG as an alternative for the relevant platform. The client interface, core, and package architecture are separate concerns. Check them in order: choose the system, confirm the processor architecture, then select the client. This prevents desktop steps from being applied to mobile devices and reduces the chance of missing menus after import.
The download page lists the four platforms separately and identifies differences such as desktop editions, the classic interface, arm64, universal packages, deb, and rpm. You do not need to understand every protocol first; choose your platform and continue to the next step.
platform=Windows → client=v2rayN
Check 02
After importing a subscription, update it manually and confirm the node list
A subscription link is not an ordinary web address; add it through the client's subscription management section. Before pasting, make sure the link is complete and has not picked up line breaks or extra spaces from a chat app. Save it, run a manual update, and check whether groups or nodes appear. If the list is still empty, read the update message first instead of repeatedly toggling the system proxy. The proxy switch cannot create node data before the subscription has been parsed.
QR-code and clipboard imports should produce the same result. If duplicate groups appear, clean up old subscriptions first and keep one clearly identified source. Future updates and troubleshooting will be easier to follow.
subscription → save → update manually → select node
Check 03
Distinguish the system proxy, TUN mode, and routing rules
The system proxy sends apps that follow the operating system's proxy settings through the client. TUN mode covers a broader range of traffic but usually requires additional permissions. Neither is the node protocol itself, and you should not switch between them repeatedly before identifying the problem. For an initial setup, start with the system proxy, confirm that the browser works as expected, then consider TUN mode if an app does not read the system proxy.
Routing rules decide which requests connect directly, use the proxy, or are blocked. Start with the client's basic rules, then add rules gradually based on domains, address ranges, and app requirements. Change one set of conditions at a time and verify immediately to prevent rules from overriding one another.
mode=system-proxy · route=rule-based
Check 04
Confirm connectivity at the process, log, and proxy-status levels
Clicking Connect only means the client has started applying the configuration; it does not mean every app is using the proxy. First check that the core process started normally, then inspect the logs for port conflicts, certificate names, DNS resolution, or configuration-field errors. Next, verify that the system proxy is enabled and that the target app follows it. Layered checks separate “the client did not start” from “the app is not using the proxy.”
After verification, record the node, mode, and rules in use. If something changes later, compare only the latest modification; there is no need to reinstall the client or reset every setting at once.
core running → log clean → proxy enabled → app test
Platform entry points
Choose a V2Ray client for your platform
Check the platform, processor architecture, and package type separately. The homepage only routes you to the right path; the download page contains the actual files.
PLATFORM / 02
macOS
When using v2rayN, open the system information first to identify the chip type. Do not determine the installer solely by the device's appearance; Apple Silicon and Intel packages are different.
PLATFORM / 03
Android
Start by checking v2rayNG's arm64 and universal packages. If you need the V2Fly core path, compare the matching architecture entry for v2flyNG.
PLATFORM / 04
Linux
Use v2rayN on desktop environments. Choose deb for Debian and Ubuntu, or rpm for Fedora, openSUSE, and other environments according to their package-management system.
Quick start
From subscription import to connectivity checks
For the initial setup, do only what is necessary. Check the result after each step instead of changing multiple switches at once.
View the complete guide →-
01
Add a subscription and update it manually
Paste the complete link under subscription management, save it, and run an update. The import stage is complete only when groups and nodes appear. If the client reports a format error, copy the original link again and check for spaces or line breaks.
-
02
Choose a node and proxy mode
Select a node before starting the core. On desktop, begin with the system proxy for an initial setup; on Android, grant network permission when prompted during connection. Keep the default routing rules for now to reduce variables.
-
03
Read the logs and verify the target app
Make sure the client reports no port, DNS, certificate-name, or configuration-field errors before testing the target app. If only certain apps fail, check whether they read the system proxy instead of immediately replacing the subscription.
Core and ecosystem
The relationship between Project V, V2Fly, and Xray
The client handles the interface and system integration; the core handles protocols, transport, routing, and connections. Keeping these layers separate makes client selection more accurate.
From Project V's configuration model to two common core families
Project V established a configuration-driven proxy ecosystem built around concepts such as inbound and outbound connections, routing, DNS, transport layers, and protocol parameters. V2Fly continues V2Ray's community-maintained development path, retaining many established configuration patterns and protocol combinations. Xray extends the same technical lineage with additional protocol and transport capabilities while maintaining its own release cadence. They share common origins but differ in supported features, so names alone are not enough to judge them.
For most client users, the first question is whether the protocols in the subscription match the client's core. VMess, VLESS, Trojan, Shadowsocks, and other types may require different parameters across cores; capabilities such as REALITY also depend on the specific core and client implementation. A successful import only means the text was recognized, not that every field can be executed by the current core. When a connection fails, check subscription-format compatibility separately from protocol-capability compatibility.
The client, core, and subscription are three separate layers
v2rayN is a desktop graphical client that handles subscription management, the system proxy, routing settings, logs, and core invocation. v2rayNG targets Android, typically follows the Xray core path, and establishes connections through the system network interface. v2flyNG also targets Android but is better suited to configurations requiring V2Fly core compatibility. All three clients are open-source software; their behavior depends on each project's maintenance cycle, platform permissions, and underlying core.
A subscription is a configuration-distribution method, not a client or a core. The same subscription may show slightly different fields in different clients because interface labels, defaults, and core support differ. When troubleshooting, record the client name, core type, protocol, and proxy mode first. That information is more useful than simply saying “it won't connect.”
OPEN SOURCE
Open source makes implementation boundaries easier to understand
Public code provides a reviewable basis for protocol handling, configuration conversion, and platform integration. Users should still choose according to their system permissions, configuration source, and use case; “open source” does not mean every configuration is automatically correct.
UPDATE PATH
Clients and cores may update independently
A graphical interface update does not necessarily change core capabilities, while a core update may affect protocol parameters and defaults. When behavior changes after an upgrade, read the client's notices first, then verify the current core type and configuration fields.
DOCUMENTATION
Read documentation by problem layer
For installation issues, read the platform documentation; for import issues, check the subscription format; for connection issues, inspect the logs and core; and for apps that still fail, check the system proxy and routing. Layered reading is more effective than repeatedly reinstalling.
Featured FAQs
Four questions to answer before configuring
These questions commonly arise during download, import, and the first connection. Review the diagnostic approach first, then open the relevant documentation.
Which v2rayN desktop edition should I choose?
Choose the desktop edition for the newer cross-platform interface; choose the classic WPF edition if you prefer the traditional Windows workflow. For either one, confirm the system architecture and runtime environment first.
View related answers →What should I do if no nodes appear after importing a subscription?
First confirm that the link is complete and update the subscription manually, then check the client's message. Do not switch the system proxy or change routing rules until the node list has been generated.
View related answers →How should I choose between the system proxy and TUN mode?
Use the system proxy for the initial setup and basic verification. Consider TUN mode only when the target app does not read the system proxy and the node and core have already been confirmed to work.
View the steps →Where should I start if the connection still does not work?
Check four layers: the core process, client logs, system proxy, and target app. Change only one condition at a time and keep a record of the latest settings that worked.
Go to Troubleshooting →Practical notes
Recent V2Ray setup and troubleshooting articles
Actionable checklists for certificate errors, Android background connectivity, and desktop client startup issues.
V2Ray TLS Certificate Error Checklist: System Time and SNI Settings
Check the system clock first, then verify that SNI and serverName match the certificate, and finally confirm the relevant port and security settings.
Read the full article →v2rayNG on Android: Connection Permissions, Battery Optimization, and Per-App Proxy
Review the relationship between first-connection permissions, background restrictions, and per-app proxy settings to reduce unexpected disconnects after locking the screen or switching apps.
Read the full article →Why Does v2rayN Crash on Launch? Runtime, Permissions, and Port Conflicts
Check the desktop runtime environment, directory write permissions, and local port conflicts in order of likelihood instead of repeatedly reinstalling without knowing the cause.
Read the full article →