Open-Source Client Guide

V2Ray GuideClient Setup Guides

Choose v2rayN, v2rayNG, or v2flyNG for your system, then follow the steps to import a subscription and configure the proxy.

01 Client setup

Subscriptions, proxies, and core settings

Import nodes into the client first, then choose which apps use the proxy and which connect directly. For your initial setup, check each step in order. If something goes wrong, this makes it easier to find the cause.

Configuration sources

Import a subscription

A subscription URL updates a list of nodes, while a share link usually contains just one. Once you have a subscription URL, create a subscription group in v2rayN, enter the URL, and update the group. Then check that the nodes appear under it. If you only have a share link, import it directly from your clipboard; there’s no need to add a subscription. Unlike entering nodes one by one, subscriptions save you from re-entering them when the source updates. Keep any manually added nodes you want to retain in a separate group so they’re easy to find after a refresh.

Traffic handling

System proxy and TUN mode

If you only need apps that follow system settings, such as your browser, to use the proxy, start with the system proxy. For apps that ignore this setting, check whether your client offers TUN mode. TUN routes traffic through a virtual network interface, which usually covers more apps, but may require extra permissions or conflict with other network tools. When testing, enable only one mode at a time and check the result in the same app. Before closing the client, make sure the system proxy has been restored so apps don’t keep connecting to a local proxy port that’s no longer running.

Outbound selection

Routing rules

Routing rules decide whether requests that reach the client use a proxy, connect directly, or go through another outbound. Start with the built-in rules, keep local network devices on direct connections, and check that the default outbound is what you expect. Split routing is useful when you need to access printers, file shares, and other services as well as use a proxy. When adding custom rules, put narrower exceptions before general rules and check whether an earlier rule takes precedence. Change one rule at a time and retest using the same app and access path to see whether it took effect.

Maintenance and recovery

Core and database updates

The client interface, proxy core, and routing databases are updated separately. If a new transport option isn’t recognized, first check whether your current core supports it. If a domain connects but uses an unexpected outbound, check the rule order and the referenced data. Save your commonly used settings before updating, then reload the client and retest with the same node. Updating only the component you need makes troubleshooting easier than changing the client, core, and database at once. If things get worse, your notes can help identify what to roll back.

Post-setup checks

If a group is empty, first confirm that you entered a subscription URL and check the update message. If other groups refresh normally, check the status of this subscription first; there’s no need to reinstall the client.

03 Open-source ecosystem

Project V, V2Fly, and Xray

Product names on client download pages, core names in settings, and protocol names at the start of links refer to three different things. Knowing which is which makes guides and error messages easier to understand.

Client
v2rayN · v2rayNG · v2flyNG
Core
V2Fly · Xray
Protocol
VMess · VLESS · Trojan · Shadowsocks

Project V is the name of the ecosystem

Project V began with V2Ray at its core, offering composable proxy, transport, and routing capabilities. Early usage revolved around configuration files and core processes. Over time, the community developed graphical clients for different systems, bringing nodes, routing, and logs—once scattered across configuration files—into a single interface. So when an installation guide says “V2Ray,” it may mean the core specifically or the broader ecosystem. Check whether the instructions refer to the app interface, configuration syntax, or communication protocol.

This distinction also helps with troubleshooting. If you can’t find the import button, start with the client guide. If the fields look right but startup reports an unreadable option, use the logs to find the documentation for your current core. Switching to a client with a different interface doesn’t necessarily change how the core processes its configuration.

Two independently maintained core projects

V2Fly continues community development of V2Ray. Xray forked from the same codebase and has evolved independently. The projects share some concepts and configuration options, but their supported features, default behavior, and release schedules don’t always match. For example, if a configuration specifies REALITY, you can’t determine compatibility from the share link prefix alone. The prefix identifies the protocol type, but not whether the core supports every transport and security parameter in the link.

On desktop, v2rayN manages configuration through a graphical interface and uses the appropriate core based on node type and client support. v2rayNG primarily uses Xray, while v2flyNG is based on V2Fly. When migrating an existing setup, note which core you used before and test a familiar node first. There’s no need to import and rewrite everything at once.

Open-source licenses and connection settings are different things

v2rayN, v2rayNG, and v2flyNG are all open-source graphical clients. Open-source licenses govern how code can be used, modified, and redistributed. Other components bundled with an installer may have their own licenses. For deployment or redistribution requirements, check the licenses for the relevant projects and components rather than applying one project’s terms to the entire ecosystem.

VMess, VLESS, Trojan, and Shadowsocks are proxy protocols recognized by clients. When importing a configuration, keep the server address, port, transport, and security settings provided by its source. Changing only the link prefix to another protocol won’t make the remote server use matching settings. A protocol name alone also doesn’t tell you how the connection is protected. For example, VLESS identifies the protocol type; check the actual security settings to determine transport protection. When asking for help publicly, describe the link prefix and error message without sharing the full link, which may contain credentials.

Update the core, client, and routing data separately

Client updates mainly change the interface and configuration management, and may also include a core update. The core reads the configuration and establishes connections; resources such as GeoIP and GeoSite provide data for routing rules that reference those categories. Resource updates may change which categories certain requests match, even if the settings interface stays the same. Conversely, downloading new data files won’t change traffic routing if no rules reference those categories.

After an update, compare results using the same node, app, and destination address. If the client won’t start, check the core logs first. If it starts but some destinations use a different outbound, check routing rule order and resource files. Keeping a record of your settings and test results before upgrading makes it easier to find the cause than resetting several options at once.

Keep configuration sources separate from service providers

Downloading a client only gives your device a way to read configuration and route traffic; the installer doesn’t provide nodes or subscriptions. If you already have a manual configuration, save a backup before importing a new group. Node names may change, and some entries may disappear after a subscription refresh. Before connecting, check which node is currently selected rather than relying on the group’s update status.

When asking for help, include your operating system, client, core, the steps that caused the error, and redacted logs. If the issue occurs in only one app, say whether you’re using the system proxy or TUN. Hide subscription URLs, server addresses, and account details in screenshots. To review the setup from scratch, follow the section for your platform in the complete setup guide.

04 Configuration guides

Recent setup guides

Once the basic settings work, explore multi-device setups, update routing resources, or check how your client and core work together.

Browse all articles →

Download clients