Choose an open-source client for your platform, follow the Chinese setup guide to import a subscription, then check proxy and connection settings based on the symptoms.
Choose an installer for your platform
Check your operating system and processor architecture first, then choose a client. Find installers on the downloads page; use the homepage to compare options and get setup guidance.
The desktop edition uses a cross-platform interface, while the classic WPF edition keeps its familiar window layout. Check your processor type in system settings before reading the installation instructions. Before switching interfaces, back up subscription groups and custom routes so you don't mistake interface differences for connection issues.
Go to downloads →Check the chip name under “About This Mac.” Apple Silicon and Intel require different installers. If a system warning appears on first launch, verify the download source and read the warning. After installation, check that your network proxy points to the client’s current local port.
Go to downloads →Start with v2rayNG, which uses the Xray core; consider v2flyNG if you specifically need the V2Fly core. Most newer Android phones use arm64; if you’re unsure of your architecture, check the universal package details. On first connection, approve the system VPN permission and check whether another app is already using the VPN slot.
Go to downloads →Ubuntu and Debian desktops generally use deb packages; Fedora and similar distributions typically use rpm. Choose the right architecture: x64 or arm64. A graphical client is suited to a desktop environment. Whether terminal applications use the proxy depends on their own configuration—not just the desktop system proxy toggle.
Go to downloads →The client reads configuration, launches a core and manages the local proxy; installation alone won’t create a working remote connection. Get a subscription URL or individual configuration from a trusted source, and check that you’re authorized to use it and that it hasn’t expired before importing it. Subscription links may contain access credentials: don’t include them in public screenshots or submit them to unknown online converters. If you need to convert a V2Ray subscription, first check which formats the target client supports and prefer an export method explicitly supported by your configuration provider.
For your first setup, run just one client, keep the default listening port and avoid adding browser proxy extensions or other tools that take over network traffic. First confirm that the subscription imports and the core starts; then enable the system proxy. Once the basic connection works, adjust split routing or TUN. Changing one thing at a time makes it easier to identify what to undo if something breaks, instead of guessing whether the node, DNS and permissions are all at fault.
Understand the connection path through each setting
Names and menus can vary by platform and version. Understand what a setting does, then look for its equivalent in your client; don’t assume desktop menus map directly to Android.
If the server list is empty or unchanged after an update, open “Subscription Group Settings” and check that the address is complete, the group is enabled and the subscription is still valid. Group subscriptions by source to avoid mixing up configurations during updates. If your current connection isn’t working, try “Update subscription (without proxy).” If the address is reachable only through a particular network path, use that route instead. After a successful update, check what was actually imported—a completed request doesn’t mean the nodes can connect. Groups make updates easier than maintaining entries one by one, but they can’t fix an expired address.
View setup guide →If the same node reaches some sites but times out on others, check which routing rule matches the destination domain. Rules are usually evaluated in order, so a broad rule can catch a request before a more specific one. “IPIfNonMatch” means the destination address is resolved and IP rules are tried only if no domain rule matches; it doesn’t mean every request is resolved first. Start with a preset you understand, then add a few custom rules and retest the same destination after each change. Routing determines the outbound path; it doesn’t test whether a node is reachable or fix remote authentication errors.
View setup guide →IPIfNonMatchThe system proxy affects only apps that honor system proxy settings; it doesn’t route every program through the client. “Set system proxy automatically” writes the local proxy address to your system settings, “Clear system proxy” removes those settings, and “Do not change system proxy” leaves them as they are. TUN takes over traffic through a virtual network interface and usually involves permissions, routing and DNS. Test a regular proxy connection first, then decide whether to enable TUN; don’t turn on multiple traffic-capture methods at once. Terminals, browser extensions and Android VPNs each have their own settings, so check the actual request path for each.
View setup guide →The graphical client and core have different roles: the client manages configuration, while the core handles protocols and network connections. In supported configurations, v2rayN can use Xray or sing-box; available options and compatibility depend on the version and platform. If you see an unsupported transport or parameter warning, note the error in the logs and check the configuration requirements before switching cores repeatedly. On Android, distinguish v2rayNG, which uses Xray, from v2flyNG, which uses V2Fly. Switching cores can resolve certain compatibility issues, but it won’t revive an expired subscription or fix invalid credentials.
View setup guide →Project V · V2Fly · Xray
Think of the client, core, protocol and subscription as separate pieces. Installing a graphical interface is only the first step; a working connection also depends on your configuration and network.
V2Ray is part of the Project V ecosystem. Its core approach uses configuration to combine inbounds, outbounds and routing into a defined path for application requests. V2Fly continues community development of V2Ray-related cores, while Xray has evolved from related code into its own implementation and feature set. They share history, but that doesn’t mean every parameter, protocol extension or configuration file is interchangeable.
Protocol names describe communication rules; the core implements them, and the graphical client organizes common operations into menus. If you see VMess, VLESS, Trojan or REALITY, check the configuration requirements and core support first. Don’t assume a configuration will work just because the client names look similar. Transport settings, TLS parameters and server-side configuration must match; changing only one side usually won’t make them compatible.
When troubleshooting, record which client and core you’re using, the connection method and the step where it fails. That’s more useful than saying “V2Ray doesn’t work.” A startup failure and a request timeout occur at different layers: check configuration and listeners first for the former, then remote access, name resolution and routing for the latter.
v2rayN is for desktop use, with server lists, subscription groups, system proxy and routing management in one place. v2rayNG is for Android, uses the Xray core and routes app traffic through the system VPN interface. v2flyNG is also for Android and uses the V2Fly core, making it an option when you specifically need its behavior or compatibility. All three are open-source clients, not different skins of the same program.
Desktop and mobile clients can use compatible configurations from the same source, but local proxy ports, background behavior and permissions differ. “Set system proxy automatically” on desktop doesn’t replace Android VPN authorization, and Android’s connect button isn’t equivalent to all desktop network settings. When switching devices, import the configuration, then check the connection method for the new device.
This site organizes download links and setup guides in Chinese; it isn’t the official development site for these projects. When searching for “v2rayN official site” or “v2rayNG official site,” distinguish between the website, the software project and the configuration provider—they have different responsibilities.
Open source means software code is available under a specific license. Use, modification and redistribution must follow that project’s terms. Clients, cores and bundled components may have different licenses; if you redistribute software, review each license separately—“open source” alone doesn’t settle the terms. Also distinguish free software from remote services that may charge a fee.
A subscription typically contains a set of connection configurations and may include server addresses, user identifiers and authentication details. Before sharing a screenshot publicly, hide subscription URLs and sensitive parameters; include only the error type, menu location and relevant environment details. Don’t publish a full subscription just so someone else can reproduce the issue. Redacted logs and a clear sequence of steps are usually more useful for troubleshooting.
An imported configuration doesn’t prove the service is active or that every app is using the proxy. Verify the source, compatibility and authorization, then test the connection with an actual request. If you see a certificate error, check the system clock, destination name and configuration match first; disabling security checks isn’t a general fix.
The graphical client, core and rule data may update independently. A new menu option doesn’t mean every existing configuration needs to change, and protocol support changes may come from the core rather than the interface. Before updating, note what currently works, back up subscription groups, custom rules and essential settings, then read the release notes for your platform.
After an update, test a minimal configuration first: start the client, confirm the core is running and use a known-good configuration to reach a fixed destination. Once the basic connection works, restore custom routing, TUN and launch-at-startup settings. If the issue began after the update, keep the exact error and steps to reproduce it. Don’t delete configurations, replace the core and reset the network all at once—you won’t know what caused the problem.
For a subscription update failure, check the address and request path first. If a webpage won’t load, check whether the client is listening and the app is using the proxy. For slow speeds, compare your network and remote server load. Working from input to output preserves more useful evidence than reinstalling repeatedly. For complex cases, see the Troubleshooting Handbook.
First, check that the list contains a usable configuration and that the right server is selected. Then review the core startup logs. If the core is running, check “Set system proxy automatically” and see whether a browser extension is overriding the setting. If only one app fails, check that app’s proxy settings instead of switching every node. Follow the setup guide to verify the connection step by step.
Identify the process using the port; don’t terminate an unknown system process. Check whether you launched the client twice or another proxy app is using the same port. If you need to change the “Local mixed-port listener,” note the new value, restart the service and update any browser or app proxies you configured manually. Changing the value in the interface won’t update old port references everywhere. See Troubleshooting.
Turn off TUN first and check whether regular proxy mode works. If it does, check the permissions TUN needs, the virtual interface and possible conflicts with other network tools—one at a time. Keep a record of your current DNS and routing settings, change one setting at a time and retest. If the network still won’t work after you exit the client, check for a leftover system proxy. See the Troubleshooting Handbook.
A subscription update requests configuration from a URL; a node connection uses that configuration to reach a remote server. They may take different network paths. First confirm the subscription URL is valid and its format is supported, then compare updating with and without the proxy. A timed-out node doesn’t necessarily prevent a direct update, and a successful update doesn’t guarantee the remote service is working. Compare your symptoms in Troubleshooting.
Tips and notes
Start with the symptom and follow the relevant instructions. Find where the failure occurs before changing settings, and record the result before and after each step.
For Ubuntu, Debian and Fedora desktop users: installation commands for deb and rpm packages, dependency fixes, desktop launchers and launch-at-startup setup. Check your distribution and processor architecture first, then distinguish installation failures from launch issues and proxy routing problems.
Read the installation guide →Covers common causes such as expired subscription URLs, unrecognized formats and requests using the wrong network path. Explains how to set the auto-update interval in subscription groups and update without a proxy. Check whether the request reaches its destination, then inspect the response—don’t mistake an error page for a valid subscription.
Read the update troubleshooting guide →If webpages won’t load even though the system proxy is set automatically, check browser extensions, system settings and terminal environment variables separately. First confirm the local listener is running, then verify the address and port each app actually uses. Browser access doesn’t prove that terminal traffic is routed through the proxy.
Read the proxy troubleshooting guide →