Add subscription
Subscription URL https://example.com/sub?token=xxxx OKImport a subscription
Save the URL first, then fetch the configuration.
- Client and setup guides
v2rayN Download Hub
Desktop client downloads and subscription setup guides. Step-by-step guidance for installing on multiple platforms, importing subscriptions, and configuring proxies—from choosing a client to testing your connection.
- Subscription groups
- Traffic routing
- Xray · V2Fly
Configuration walkthrough
Five ways to configure v2rayN
Subscriptions provide the configuration, the system proxy routes apps into the client, and routing rules choose the outbound path. Each has a distinct role, so there is no need to change everything on first launch. Start by updating the subscription and testing a browser connection, then add rules as needed for specific apps. Changing settings one at a time makes problems easier to diagnose.
The window below is a static illustration, not an interactive client. Select a tab to see what each setting does. Menu names and locations may change between client versions, so check the settings in your installed client when following these steps.
Add subscription
URL · Example for illustration https://example.com/sub?token=xxxx OKSubscription import is useful for managing configurations provided by a service. In Subscription Group Settings, enter a group name and the full URL, save it, then select Update All Subscriptions. Choose a configuration from the list once the update finishes. Unlike pasting individual shared links, subscription groups make it easier to sync changes later. Updates still depend on a valid URL, network access, and an active service. Tokens in subscription URLs often grant access; keep them out of public screenshots and never submit them to untrusted conversion sites. If the list is empty after an update, check the update log before reinstalling the client.
- Set system proxy automatically
- Clear system proxy
- Leave system proxy unchanged
System proxy mode directs apps that follow system settings to the client's local proxy port. To test a browser for the first time, select Set system proxy automatically. Clear system proxy removes the proxy settings from the system; Leave system proxy unchanged preserves existing settings—it does not turn the proxy off. Unlike TUN mode, which captures network traffic, a system proxy works only when an app reads those settings. Terminals, games, and browsers with their own proxy settings may need separate configuration. When troubleshooting, first confirm that the client core is running, then check the app's own proxy options so an access issue is not mistaken for an invalid configuration.
Route private addresses directly
geoip:private→direct
Routing rules select a direct, proxy, or blocked route based on domains, addresses, or other conditions. In this example, geoip:private matches private addresses and direct means a direct connection, helping preserve access to local network devices. Traffic routing requires attention to rule order, domain resolution, and the default outbound route—not just sending every destination through the same route. Start with a preset that fits your needs, then add only a few clear rules. After each change, test a destination website and a local network service. If only one site has a problem, check which rule it matches before changing all DNS settings or switching every configuration.
Traffic capture
Enable TUN mode
TUN mode settings →
TUN mode captures traffic through a virtual network interface, making it useful for apps that ignore system proxy settings. The difference is where traffic is captured; it does not mean every destination will use a proxy. Routing rules still determine the outbound path. Before enabling TUN on desktop, confirm that you have the required permissions; on Windows, this usually means running as administrator. Also check for other virtual network interfaces and networking tools. Try TUN only after a standard system proxy connection works, so you are not troubleshooting two access methods at once. If local network access or DNS resolution fails after enabling it, turn TUN off to compare, then check private address rules and DNS settings.
Core type
- Xray
- V2Fly
The client provides the interface and manages configuration; the core handles the actual network connection. Switch cores to address compatibility issues with a protocol, transport method, or specific setting—not as a mandatory step whenever a connection fails. Xray and V2Fly are related projects that have developed separately; check their release notes for current compatibility. Available options in the client also depend on what is installed. Before switching, note your current settings and make sure the target core supports your configuration. Then restart the connection and check the logs. Changing cores usually will not fix a problem caused by the subscription URL, system proxy, or server status.
Choose an installer
Choose a client for your operating system
Use v2rayN on desktop. For Android, start with v2rayNG; consider v2flyNG if you need a V2Fly core. Check your operating system and processor architecture, then choose the matching package on the download page. Desktop installers do not run directly on phones, and you should confirm with your service provider that a subscription URL supports the client you plan to use.
These links open the matching platform section on the download page; they do not start a file download. The download page explains package types, installation requirements, and client differences, making it useful to check before installing for the first time or switching devices. The clients are free to use, but they are tools for managing configurations and connections. You still need a valid configuration or subscription.
Windows
The desktop edition uses a cross-platform interface and offers a consistent workflow. The Classic WPF edition retains a familiar desktop layout. Both are designed for managing subscriptions, selecting configurations, and adjusting routing. Choose based on your system and interface preference; you do not need to install both.
Before installing, check your system architecture and the runtime requirements on the download page. For everyday browser access, start with the system proxy. Consider TUN only if an app ignores system proxy settings. Before switching interface editions, keep any configuration you need—especially subscription groups, custom routing rules, and port settings—to avoid overwriting your existing setup.
macOS
Check your chip under About This Mac, then choose the Apple Silicon or Intel download. Matching the package to your processor is the first step; do not rely on the device's appearance or purchase year. After launching the client, import a subscription and select a configuration, then check that the proxy appears as expected in your system network settings.
If the system asks you to confirm the app's source, first verify where you downloaded the installer, then follow the system instructions. Do not disable system-wide security just to launch the client. System proxy settings may coexist with an app's own proxy configuration. If only one browser has a problem, check its extensions and connection settings first.
Android
v2rayNG uses the Xray core, while v2flyNG uses the V2Fly core. Choose based on the protocols your configuration requires. Most newer phones can start with the arm64 package; if you are unsure of your device architecture, check your device details and the download page for a compatible general-purpose package. These are separate apps, not core components that automatically complement each other after installation.
Import and update a subscription, select a configuration, then start the connection. On first connect, Android usually asks you to authorize the VPN connection. If the connection drops when you leave the app, check battery optimization and background activity restrictions. These system behaviors are separate from subscription validity, so test them independently instead of repeatedly deleting a group that imported successfully.
Linux
Ubuntu and Debian users generally choose the deb package; Fedora users and other distributions that support it generally choose rpm. Check the processor architecture as well. This link is for the graphical desktop client, suited to desktop environments where you manage subscriptions and routing in a window. After matching the package format to your distribution, check the desktop environment and runtime dependencies.
Whether the system proxy affects an app depends on the desktop environment and how the app reads proxy settings. If a browser works but a terminal connects directly, check the terminal tool's own proxy configuration before assuming the installation failed. Configure startup at boot, startup after login, and network features that require elevated permissions separately to avoid connection issues caused by startup order.
Quick-start preview
From subscription import to connection test
Keep your first setup simple: one valid subscription, one selected configuration, and one clear way to route traffic into the client. Establish a repeatable connection before adding automatic updates, custom routing, or TUN. That makes it easier to tell whether a new setting caused a problem or the original connection conditions changed.
View the full guide →-
Add a group and update the subscription
In the desktop client's Subscription Group Settings, enter a name and URL, save them, then update the subscription. On Android, prepare the same details in subscription settings before updating. A subscription URL and an individual configuration share link serve different purposes; do not choose an import option just because a link looks long. After the update, check that configurations appear in the list and that there is no update error.
If the URL saves but no content is fetched, check for extra spaces or line breaks, and make sure no parameters are missing. Then check the service status and update log. Avoid changing routing, DNS, and core settings at the same time; otherwise, it is hard to tell which change made a difference.
-
Select a configuration and choose how traffic connects
Choose a configuration from the updated list. On desktop, start the core and select Set system proxy automatically. On Android, start the connection and approve the system prompt. System proxy and routing mode are different settings: the former determines how an app's requests reach the client; the latter decides which outbound route those requests take.
Keep the existing default routing rules for now; you do not need to add rules one by one for a first test. If another proxy or virtual networking tool is running, check whether it changes the same system settings or uses the same local port. If needed, close it temporarily and test again for comparison.
-
Test websites and other apps separately
Open a destination that should use the selected outbound route, then check that regular websites and local network services still work. A successful startup message only confirms that the local process is running; it does not prove the remote connection works. Check actual access results and logs, and do not treat one test as proof that every app is using the proxy.
If a browser works but a terminal does not, check whether the terminal reads system proxy settings. If all destinations fail, check the core log and configuration. If only domain names fail, investigate DNS resolution. Once the connection is stable, configure startup and note which access method works.
Clients, cores, and the open-source ecosystem
How Project V, V2Fly, and Xray fit together
Understanding the roles of the client and core helps you make sense of installation guides and error logs. Seeing the same protocol name in different interfaces does not mean every option is identical across clients. Likewise, installing a graphical client does not provide a working remote service. When choosing tools, verify the interface, protocol support, and configuration source separately.
Ecosystem overview
Project V: background on proxy protocols and tools
Project V is part of the ecosystem behind many V2Ray-related tools, covering proxy protocols, transport methods, routing, and configuration. The term “V2Ray client” is often used broadly for graphical apps that manage related configurations; it does not necessarily refer to a single installer. Desktop and Android clients have different interfaces, but both pass your chosen configuration to a core that handles the connection.
That is why subscription import guides may follow similar steps, while the exact settings depend on the client. When working with protocol names, transport methods, and encryption parameters, do not copy values just because another app has a setting with the same name. Check the server requirements and confirm that the client and core support the required combination. This is more effective than toggling unrelated options at random.
Core families
V2Fly and Xray: independently developed implementations
V2Fly maintains V2Ray-related implementations, while Xray is a separate core project developed from related technical foundations. The two share some protocol background, but their feature support, configuration fields, and development pace are not identical. If you see “Xray core” or “V2Fly core,” that refers to the connection engine—not the interface design or a guarantee of service quality.
Let your configuration requirements determine whether to switch cores. For example, check compatibility if the logs say a field is unrecognized or a transport combination is unsupported. If the system proxy was not applied or a subscription update timed out, investigate the access method and network path first. A core that can parse the configuration does not guarantee that the server is online.
Three open-source clients
What v2rayN, v2rayNG, and v2flyNG do
v2rayN is for desktop and provides tools for managing subscriptions, selecting configurations, setting the system proxy, and configuring routes. v2rayNG is for Android and uses the Xray core. v2flyNG is also for Android and offers the V2Fly core. All three clients are released as open-source software; whether a client is suitable depends on your device, configuration requirements, and the specific release.
Open-source licenses set the terms for using, modifying, and distributing software; they do not describe subscription plans. Clients, cores, and bundled components may each have their own licenses. Read the relevant license before redistributing or modifying software. Most users only need to check system requirements and follow the setup steps; importing a subscription does not require building or modifying source code.
Updates and configuration maintenance
Software updates vs. subscription updates
Software updates can change the interface, fix issues, or add feature support. Subscription updates fetch the latest configuration published by your service provider. They are separate operations. When subscription details change, update the relevant group first. If you encounter a clear client compatibility issue, review the release notes and consider a software update. Reinstalling should not be the first response to every problem.
Before updating the software, keep your custom routing rules, subscription groups, and essential settings, and note where sensitive URLs are stored. After the update, retest the browser, other apps, and local network access using the same connection method. Then restore custom settings gradually. For version differences, log messages, and common settings, see the FAQ and the symptom-based troubleshooting guide.
Configuration guides
Protocols, system proxy, and DNS troubleshooting
Once your basic connection works, read the guide that matches the issue you encounter. Protocol guides help identify configuration types; system proxy guides distinguish how browsers and terminals connect; DNS guides explain the path taken by domain lookups. Retest the same destination after each change to see whether it helped.
How to test for DNS leaks in V2Ray and configure v2rayN to prevent them
Use test results to identify where DNS queries are sent, then distinguish local DNS, remote DNS, and DNS interception under TUN. Test again after making changes; changing one setting alone does not guarantee that all DNS results will behave as expected.
VMess vs. VLESS: a quick guide to the protocols before choosing a server
Understand VMess and VLESS by looking at their roles, time requirements, and supported transports. Learn to recognize shared links and configuration fields, then check whether your client supports what you need. A protocol name alone does not determine connection performance.
v2rayN system proxy not working? Troubleshoot browsers and terminals separately
For browser issues, check the system proxy, extensions, and PAC settings. For terminal issues, check environment variables and the tool's own proxy configuration. Test each access path separately to locate the problem in the app settings, local port, or remote connection.