Project V ecosystem · Client guides

V2Ray OSS HubClient and routing guides

Choose an open-source client for your platform, then follow each step from subscription import to traffic routing.

01 Ecosystem overview

GUI clients and proxy cores

The client edits and manages configuration; the core establishes connections, handles requests, and applies routing rules. A client opening successfully does not mean the core has started correctly.

  • Project VV2Ray originated with Project V. Inbound, routing, and outbound settings are configured separately, which also helps pinpoint issues when reading core logs.
  • V2FlyThe community continues to maintain the V2Ray core. When using v2flyNG, check protocol and rule fields against the core actually in use.
  • XrayDeveloped as a fork within the V2Ray ecosystem. For settings such as REALITY, check the relevant Xray documentation.
  • MPL-2.0The open-source license used by V2Fly's V2Ray core and Xray-core. Each client has its own license terms.

02 Configuration flow

Subscriptions, proxy modes, and routing rules

Check each step separately: where the configuration comes from, how traffic is captured, and which rules match. When something goes wrong, identify the layer first, then adjust the relevant setting.

Set exceptions first, then choose the default outbound

In v2rayN's routing settings, first check which rule set is active, then review the outbound selected by the matching order. The core typically uses the first matching rule, so put LAN direct rules and blocks for specific domains ahead of broader rules. Check domain and IP conditions separately; adding both to one rule does not mean either condition can match on its own. After making changes, send a new request and check the logs to confirm its outbound route. Don't rely only on whether the page opens to decide if routing is working.

Outbound mapping example; the default outbound depends on your configuration
geoip:private             → direct
geosite:category-ads-all  → block
geosite:cn                → direct

03 Choose an installer

Download for your OS and architecture

Choose your operating system first, then check the processor architecture. Use v2rayN on desktop; on Android, choose v2rayNG or v2flyNG based on the core you need.

Windows

v2rayN Desktop / WPF

For a first install, start with the Desktop edition. If you're used to the WPF interface, choose the classic WPF edition. The main differences are the interface and packaging, not the proxy protocols. Check your system type in system information, then prepare the runtime environment as directed on the download page.

Launch the app from its complete extracted folder; don't move just the executable to your desktop and run it on its own. Before migrating, back up user data from the old folder, then test whether the new app can read your groups and nodes. If the interface doesn't appear after you double-click, check the runtime, folder write permissions, and security software logs before importing subscriptions again.

Go to downloads

macOS

v2rayN Apple Silicon / Intel

Check the chip or processor listed under About This Mac. Choose arm64 for Apple Silicon and x64 for Intel. Don't guess based on the model's appearance or purchase year; different generations of the same product line may use different chips.

After installation, test that the client can start the core using a known-working configuration. If a browser works but a particular app can't connect, check whether it uses the system proxy. For apps with their own proxy settings, verify the local address, listening port, and proxy type separately. Don't reuse settings left behind by another client.

Go to downloads

Android

v2rayNG / v2flyNG

v2rayNG uses the Xray core. Choose v2flyNG only if you specifically need the V2Fly core. If your device supports arm64-v8a, you can use the arm64 package. If you're unsure which architectures your device supports, try the universal package, while still checking the system requirements.

The first time you start the proxy service, approve the VPN connection when prompted. If another app is already using the device's VPN slot, stop its connection before testing. If the connection drops when the screen locks, check VPN status, background restrictions, and network switching history separately. Don't assume the remote node is down based on this alone.

Go to downloads

Linux

v2rayN deb / rpm

For Debian- and Ubuntu-based distributions, choose deb. For Fedora and other distributions that use RPM, choose rpm. Package format and processor architecture are separate requirements. x86_64 corresponds to x64, and aarch64 corresponds to arm64; choosing a different package format won't fix an architecture mismatch.

After installation, test with both a desktop app and a terminal program. The desktop environment's system proxy may not affect terminal programs, and some tools use their own proxy settings or environment variables. If only the terminal fails, check which settings it actually reads. If both fail, check that the core has started and opened a local listener.

Go to downloads

04 Open-source ecosystem

How Project V, V2Fly, and Xray relate

To determine whether a configuration can be migrated, check the client, core, and rule sets separately—not just the node name or import result.

How a request flows through the core

inbound → routing → outbound

The client generates or loads the configuration; the core routes incoming requests to an outbound based on the routing rules.

Explore core and routing terminology

About the scope of this site's guides

  1. Project V: the configuration model from inbound to outbound

    Project V is where the V2Ray ecosystem began. Its configuration model is useful for everyday troubleshooting: inbound accepts requests, routing decides which outbound handles the traffic, and outbound connects directly, forwards traffic, or rejects it according to the configuration. A node list in a GUI client is only part of the configuration; it doesn't show that every app's requests will enter the core. For example, a browser and a command-line tool on the same machine can have separate proxy settings, so requests to the same address may take different paths.

    Even when the desktop interface shows a selected node, check two things separately: whether the core successfully opened a listener, and whether the target app actually sent its request to that listener. If the target request doesn't appear in the logs, check how the app connects first. Changing remote transport settings repeatedly won't reroute traffic that never reached the core.

  2. V2Fly and Xray: shared configuration concepts, different implementations

    The community continues to maintain the V2Ray core as V2Fly. Xray branched from this technical lineage and has developed as an independent project. Both share basic concepts such as inbound, routing, and outbound, but protocol, transport, and security fields evolve with each implementation. If a client can parse a share link, that only means it recognized the link; it doesn't prove that the selected core supports every parameter or that the remote end uses the same combination.

    When migrating, check the protocol, transport, and security layers before choosing a client and core. For REALITY, for example, verify the security settings against the relevant Xray documentation. A protocol name shown in a share link isn't a complete configuration. If a standard configuration connects but a particular node reports an unsupported setting, keep the full error details and check that node's fields against the core implementation first.

  3. What the three open-source clients manage

    v2rayN is a desktop GUI client for managing subscriptions, service settings, proxy modes, and routing. The cores it can use depend on the selected build and configuration. v2rayNG is for Android and primarily provides an interface for Xray configurations; v2flyNG is also for Android but uses the V2Fly core. All three manage nodes, but their interface options, import formats, and default routes aren't interchangeable.

    You don't need to install both Android clients to get started. Choose a core that supports your node, then import one configuration and run a basic test. To compare the clients, keep the network and destination the same, and make sure only the client being tested has its VPN service running each time. This helps distinguish differences in the client, core, or traffic capture method.

  4. Open-source licensing and community releases

    The V2Ray core maintained by V2Fly and Xray-core use MPL-2.0, a file-level open-source license. If you distribute modified covered code, you must meet the license's applicable source-code requirements. Clients and cores are separate projects, and other bundled components may have their own licenses. When reviewing or redistributing software, check the license notices included with each project and component. Don't assume a core's license covers the entire client.

    The community maintains the interface, core implementation, and rule data separately. Setting names in the guides help you find features; they don't mean every interface has the same layout or that updating a client also refreshes subscriptions and rule sets. When choosing a package, check the OS, architecture, and core support. When troubleshooting, refer to the local configuration and actual logs.

  5. Subscriptions, rule sets, and clients update separately

    Updating the client changes the program; refreshing a subscription changes the node source; updating rule sets changes the matching data. Handle these separately. Before updating, keep a working configuration and note the current rule set and local listening port. Afterward, test the same destination again, then verify that local services still connect directly and requests that need a proxy still take the expected route.

    If only certain configurations fail after a subscription update, compare their transport settings first. If a rule-set update changes routing for only certain domains, check whether categories changed or an earlier rule now matches first. If all requests fail after a client update, check core startup and listener errors. Narrowing the search to what changed is more effective than reinstalling, refreshing subscriptions, and changing DNS all at once.

05 News and troubleshooting

Recent configuration and troubleshooting articles

For startup failures, check the local listener first. For installation failures, verify the package. For unexpected traffic routing, check routing rules and rule sets.

V2Ray Local Port Conflict: Find the Process and Change the Listening Port

Use built-in system commands to identify the processes using ports 10808 and 10809. Learn how to change v2rayN's local SOCKS and HTTP listening ports, and which settings to update afterward.

Before changing a port, check whether it's being used by a running client. If it's an old instance, closing it and restarting the client is usually simpler than changing the configuration. If you need to keep both programs running, assign each a different port. Afterward, test with the same app and make sure it isn't still using the old proxy address.

How to Install and Configure v2rayN on Windows: WPF or Desktop?

Follow the process from package selection and extraction to first launch and subscription import. Compare the WPF and Desktop editions, and learn how to handle common issues such as missing runtimes, antivirus blocks, and non-ASCII paths.

Use first launch as the dividing line: if the interface doesn't appear, check the runtime environment; if it opens but no nodes appear, check the import and subscription update. These issues have different symptoms and need different checks.

How to Update GeoIP and GeoSite Rule Sets and Write Routing Rules

Learn what geoip.dat and geosite.dat are for, where to update rule sets in the client, and how to combine common entries such as geosite:cn and geoip:private in routing rules.

To test rules, prepare one request using a domain and another using an IP address directly. If only one routes incorrectly, first check whether the rule type matches the request.

Download clients