Start by importing a subscription, then configure system proxy and routing. Choose a free, open-source client for your platform, and use logs to troubleshoot connection issues.
Subscription groups
Xray · V2Fly ecosystem
GUI configuration
v2rayN
−□×
ServersSubscription groupsSettingsReloadCheck for updatesHelp
TypeAliasAddressPortTransport protocol
Set system proxy automatically ⌄Routing: bypass mainland China ⌄
‹ v2rayNG Settings
Allow connections from the local network
Enable sniffing
Enable local DNS
Routing settings›
Subscription group settings×
Alias
Enter a group name
Optional URL
https://example.com/sub
✓Enable updates
Auto-update interval (minutes)
OKCancel
SUBSCRIPTION
Manage subscription URLs as configuration sources Importing does not mean you're connected
SYSTEM PROXY
System proxy determines which apps connect First check whether the app uses the proxy
ROUTING
Routing rules determine where connections go Then check whether a rule matches
v2rayN subscriptions and proxy settings
Follow the connection path to understand the settings: configuration source, app entry point, routing destination, and finally TUN capture.
After opening the client, avoid changing every setting at once. The server list stores configurations, subscription groups handle bulk updates, and the system proxy makes a local proxy endpoint available to apps. Each has a different role: a configuration in the list does not mean your browser is using the proxy, and enabling the system proxy does not mean the selected server can connect. Test each layer separately to pinpoint the problem.
Save a subscription group before updating the list
Open “Subscription group settings,” enter a recognizable alias, and paste the full V2Ray subscription link into “Optional URL.” Save it, then select “Update current subscription.” The group links the URL to your server list, so future updates save you from copying individual share links. Subscriptions are more convenient than manual imports for receiving configuration changes, but updates replace entries in the group. Back up any configurations you edited before updating, then check the logs and group filter. Subscription links may contain access credentials, so don’t include them in public screenshots.
Subscription groups → Subscription group settings → Update current subscription
Subscription group settings · illustration
Alias
Everyday use
Optional URL
https://example.com/sub
✓Enable updates
The example URL is for illustration only; it does not provide a subscription service.
Connect apps that follow the system proxy
Select a server and set it as active, then choose “Set system proxy automatically” from the system proxy menu at the bottom. This option changes the operating system’s proxy settings, allowing apps that follow those settings to connect to the client’s local port. It does not guarantee that the server is reachable or that every program will use the proxy. System proxy settings are an easy starting point for desktop browsers, but check terminals, games, and apps with their own proxy settings separately. When you’re done, choose “Clear system proxy” so apps don’t keep trying to connect to a client that has exited.
Main window footer → System proxy → Set system proxy automatically
System proxy · illustration
Clear system proxy
Set system proxy automatically
Check separately whether apps follow the system settings.
Choose direct or proxied connections by destination
First confirm that the app is using the client, then select a preset from the routing menu at the bottom. “Bypass mainland China” routes some connections directly according to its rules, while “Global” generally sends regular traffic through the proxy. The generated rules determine the exact behavior. Routing chooses where traffic goes; it doesn’t make an app use the proxy in the first place. Split routing can handle local services and proxied traffic separately, without relying on a global preset. When editing custom rules, check their order, domain matching, and DNS results. Change one setting at a time, retry the same destination, and watch for changes to the outbound route in the logs.
Main window footer → Routing → Select a routing preset
Routing presets · illustration
Bypass mainland China
Blacklist
Global
Preset names and available rules depend on the current interface.
Capture traffic that doesn’t follow the system proxy
Get a basic connection working with the system proxy before enabling TUN. TUN uses a virtual network interface to capture eligible traffic, covering more apps than changing system proxy settings alone. It also relies more heavily on permissions, routing, and DNS configuration. Before enabling it, note your current settings and make sure no other network tool is taking over the default route. Windows typically requires administrator permissions; on other desktop systems, follow the client’s prompts. After enabling TUN, test websites, local devices, and name resolution separately. If the network goes down entirely, disable TUN to restore the baseline and check the logs before adding more changes.
Main window footer → Enable TUN → Check logs
Before capturing traffic · illustration
Enable TUN
Test the active server first, then check permissions, the virtual network adapter, and DNS. TUN is off in this illustration; that doesn’t mean it should always be off.
Choose a V2Ray client for your platform
Use v2rayN on desktop. For Android, start with v2rayNG and consider v2flyNG if you need a V2Fly core.
Before downloading, check your system information to confirm the processor architecture, then choose the package type. Similar client names don’t mean their packages are interchangeable, and desktop and Android versions of the same client have different interfaces. These links take you to the download page for each platform, where you can also review installation instructions and available options. Don’t judge a package by its file size: architecture, operating system, and package format are what matter.
Choose v2rayN. The download page offers a newer cross-platform desktop interface and the classic WPF version. Pick one based on your preferences and system requirements; you don’t need both for your first subscription import.
Go to Settings → System → About to check your system type. Keep the companion files the client needs after installation. If you see a startup warning, follow the runtime instructions on the download page. For your first connection, test with the system proxy and configure TUN only after the basic connection works.
Choose v2rayN and select the package for Apple Silicon or Intel. Open About This Mac to see whether it lists a chip name or an Intel processor, then use the matching download link.
If macOS shows a security warning on first launch, verify the file’s source and follow the on-screen instructions. Don’t disable system-wide protections just to launch the app. Subscription imports work much like they do on other desktop systems, but follow your system’s prompts for network permissions, proxy settings, and TUN authorization.
Start with v2rayNG, which uses the Xray core. If you need a V2Fly core, consider v2flyNG instead. Most newer devices use arm64; if you’re unsure of your architecture, check the universal package details.
After installation, add a subscription group, update the configuration, select a server, and then connect. Android will ask for permission to establish a VPN connection; this is how the app captures local traffic. If the connection drops frequently in the background, check battery optimization and background activity restrictions instead of repeatedly updating the subscription.
Choose v2rayN, then select a deb or rpm package for your distribution. The download page provides options for arm64 as well as the more common x64 architecture. Match both the processor architecture and package format.
First check your desktop environment and distribution requirements, then install the package using your system’s software installer. System proxy settings may work differently across desktop environments. If your browser connects but your terminal doesn’t, check each program’s proxy settings rather than assuming the client failed to start.
Get one configuration working reliably before adding routing rules or traffic capture.
Have a client and a subscription URL you’re authorized to use. The client reads configurations and establishes connections; it doesn’t create remote servers. An empty list after installation is normal. These steps focus on the v2rayN desktop interface. In v2rayNG on Android, subscription groups, active configurations, and connection permissions are handled in the mobile interface. Menu locations may vary, but the goal of each step is the same.
01 / Configuration source
Add a subscription and confirm the update
Go to Subscription groups → Subscription group settings, add a group, and save an alias and the full URL. Return to the Subscription groups menu and select “Update current subscription.” Continue only after the update completes and entries appear in the list. Clicking OK only saves the URL; it doesn’t confirm that the URL works.
If the list is still empty, clear any unnecessary group filters and check the logs. An expired URL, a login page in the response, an incompatible format, or a failed network request can all result in an empty list. When copying the URL, make sure it doesn’t include line breaks, spaces, or punctuation added by a chat app. Don’t post your subscription URL in a public forum; describe the error and hide any sensitive details.
Select the server you want to use from the list, then set it as active from the right-click menu. Next, choose “Set system proxy automatically” at the bottom of the main window, and start with an existing routing preset that fits your needs. For your first connection, there’s no need to enable TUN, change DNS, and add custom rules all at once. Keeping the setup simple makes troubleshooting easier.
Make sure the client is still running, then test with a browser. Browser extensions that manage proxies independently may override system settings, and apps with custom network configurations may not use the system proxy. Check the app’s settings before reinstalling the client. Before exiting, clear the system proxy to prevent apps from continuing to point to a local port that’s no longer active.
Test the same destination repeatedly, check whether the page finishes loading, and then review the client logs. Latency results in the list reflect only the specific test conditions; they aren’t real download speeds and can’t replace a full page load test. If the homepage opens but its resources fail to load, check the routes and DNS results for those domains too.
If you can’t connect, first check whether the core started correctly, then look at the server connection, DNS resolution, and app entry point. Change one thing at a time and record the results before and after. If switching servers fixes the issue, the remote configuration or route is more likely at fault. If every server fails, check the local network, proxy port, and conflicts with other network tools first.
Project V provides background for understanding the V2Ray ecosystem. As the community grew, V2Fly continued maintaining related projects, while Xray developed along a separate core track. They share some concepts, but their feature development, protocol extensions, and configuration requirements aren’t identical. When searching for the “V2Ray official website,” first work out whether you need project documentation, client instructions, or a page for configuring a remote service.
Graphical clients provide a server list, subscription management, and settings; the core processes network connections according to the configuration. So if the interface recognizes a share link, that only means it parsed part of it. At startup, the core must also support the link’s protocol, transport, and security parameters. When asking about compatibility, specify the client and core separately instead of just saying you use “V2Ray.”
Open-source licenses and usage boundaries for three clients
v2rayN, v2rayNG, and v2flyNG are all free, open-source clients. v2rayN is for desktop use, with settings for subscription groups, system proxies, and routing. v2rayNG is an Android client that uses the Xray core. v2flyNG is another option for Android configurations that need the V2Fly core. Open source means the code is available under the project’s license; it doesn’t mean the client comes with working servers or guarantee the quality of any subscription service.
Licenses need to be considered separately for each component. The v2rayN and v2rayNG clients use GPL-family licenses, while the V2Fly and Xray cores use MPL-family licenses. The client, core, and dependencies are separate software components. For everyday use, open-source licensing offers insight into how a project is maintained. If you plan to modify, redistribute, or integrate a component, read its specific license and notices rather than assuming a single “open-source” label covers every obligation.
Same protocol, but check every parameter
Names such as VMess, VLESS, and Trojan describe only part of a configuration. Transport, TLS settings, server name, path, and other security parameters can all affect connectivity. For example, when importing a VLESS configuration, don’t keep only the address and port and treat the remaining fields as optional extras. For features such as REALITY, confirm that the core supports them and that your settings match the server. If a configuration won’t run, check its fields and core compatibility instead of switching clients based on the protocol name alone.
A subscription isn’t necessarily a single file format. Some return multiple share links, others return an encoded collection of links, and some provide native configurations. Graphical clients vary in the formats they can recognize; native JSON configurations and link lists aren’t interchangeable. If the source offers multiple formats, choose one that matches your client and check the import logs. Don’t submit subscriptions containing authentication details to an online conversion service you don’t trust.
Treat updates as three separate tasks
Updating the client, updating the core, and updating the subscription solve different problems. A client update affects the interface and configuration management; a core update affects connection handling and protocol support; a subscription update fetches new server parameters. If the list is out of date, update the subscription first. If a configuration reports an unsupported feature, check the client and core compatibility notes. Confusing these three updates can introduce new variables without fixing the actual problem.
Community-maintained software keeps changing, and tutorial menus may move. Before updating, back up important configurations and custom rules, read the release notes, and update one component at a time. Afterward, retest a destination that worked before trying new features. Older screenshots can help explain the steps, but check the current client for menu names, routing options, and permission prompts.
A browser that can’t use the proxy and a terminal that ignores it are different issues. Check the system proxy status, browser extension conflicts, and terminal environment variables separately.
Learn how Base64 subscriptions, native JSON configurations, and vmess:// and vless:// share links differ, and how to import and convert them in v2rayN.
Explore how the Xray and V2Fly core branches emerged, compare support for features such as XTLS Vision and REALITY, and learn when to choose v2rayNG or v2flyNG.