The GUI client organizes your configuration; the core handles the actual connection. Import server details first, choose which apps use the proxy, then check routing and DNS. Avoid changing everything at once.
A subscription fetches server configurations in one place; an individual share link imports a single entry. In v2rayN, add the URL under “Subscription Group Settings,” save it, then update the subscription. In v2rayNG, open the menu and choose the setting with the same name. Import a copied share link from the clipboard; a webpage title is not a configuration. After importing, check the group, protocol, and address, then select the server you want to use. If an update fails, keep the existing entries and check that the URL is complete rather than repeatedly deleting the group. Subscription URLs may contain access credentials, so redact them in screenshots.
v2rayN
Subscription Groups → Subscription Group Settings → Add
Save Group → Update Subscription
v2rayNG
Menu → Import from Clipboard
Routing determines which outbound handles connections that have already reached the core; it does not automatically send apps through the proxy. For a first setup, try “Bypass LAN” to keep local device addresses on a direct connection, then add domain rules as needed. Rules are usually evaluated in order, so broad conditions near the top can override more specific ones below. When editing custom rules, outbound tags must match the active configuration; copying field names alone is not enough. Routing controls traffic inside the core, while the system proxy determines which apps send traffic to it. If an app never reaches the core, changing routing rules will not change its connection path.
In v2rayN, “Set system proxy automatically” points the system proxy to the client’s local listening port. Apps such as browsers that honor this setting will then send traffic to the core. “Clear system proxy” removes the system proxy setting; it does not delete server configurations. Global proxy in routing determines the outbound for traffic that has reached the core. These settings are not interchangeable. Some apps need a proxy configured separately, and TUN is another way to route traffic. For your first setup, verify the system proxy path before enabling multiple traffic-capture methods. If the network stops working after you exit, check whether a system proxy setting was left behind.
System Proxy → Set System Proxy Automatically
Routing → Bypass LAN
When you're done:
System Proxy → Clear System Proxy
The core handles protocol handshakes, transport, and routing; the client interface is where you manage the configuration. v2rayNG primarily uses Xray, while v2flyNG targets the V2Fly core ecosystem. The cores available in v2rayN depend on the release and protocol type. Before switching, check the protocol, transport, security layer, and any extension fields together; similar names do not guarantee compatibility. For example, REALITY is a security-layer technology, not a standalone protocol equivalent to VMess. After changing cores, regenerate the configuration and check the logs. Review custom JSON separately as well.
Check in this order
Protocol → Transport → Security layer
↓
Core support in your current setup
Check DNS resolution and connection paths separately
DNS translates domain names into addresses. The DNS server used for resolution and the outbound used for the connection are separate concerns. Browser Secure DNS, the system resolver, and the core’s built-in DNS may all be active at once. Changing one client setting does not mean every app uses the same resolution path. If a domain fails to load, note the error and check whether the app is using the proxy first. Then verify that the DNS server is reachable, routing can resolve the domain, and IPv6 is available if needed. The snippet below only shows the built-in DNS server field; it is not a complete, working configuration and does not replace routing settings.
Successful DNS resolution doesn't guarantee a connection
PLATFORM SETUP / DOWNLOADS
Choose a client for your operating system
Check your operating system first, then your processor architecture. Each link opens the download page for that platform. Desktop and Android use different clients, so don't choose an installer based on a similar-sounding name.
v2rayN comes in two interface options: Desktop and classic WPF. Desktop uses a cross-platform UI framework, while WPF retains a familiar desktop workflow. Both still require subscription imports and proxy setup. When installing, follow the download page instructions for your system and runtime requirements. Don't assume the settings work the same way in both interfaces.
Extract the package to a separate directory you can write to; don't run it from inside an archive utility. Before migrating an existing setup, close the old instance and back up its configuration. Then check for conflicts on the local listening port. If startup fails, review any runtime requirements before changing proxy settings.
Check your chip under “About This Mac”: choose Apple Silicon for an Apple chip or Intel for an Intel processor. After installation, move the app to a permanent location, then respond to any security and network permission prompts. Choosing the wrong architecture may prevent the app from starting; changing your subscription won't fix it.
System proxy settings and broader traffic routing require different permissions. For your first setup, verify the basic proxy connection first. If macOS asks to verify the developer, confirm the download source and read the system prompt before following the relevant guide. Don't disable system protections in bulk just to dismiss a warning.
Start with v2rayNG, which uses the Xray core. Consider v2flyNG if you need a setup based on the V2Fly core. Most newer devices can use arm64; if you're unsure of your device architecture, check the system information or choose a universal package. Each client manages its own configuration, so installing the other one won't automatically migrate your subscriptions.
On first connection, you'll usually need to approve the system VPN permission. If a background connection stops, check battery optimization and background activity restrictions before changing protocol settings. Make sure you know which app is handling the VPN at any given time. When testing is done, disconnect apps you aren't using so that conflicts between them aren't mistaken for a server problem.
Choose deb or rpm based on your distribution's package manager, then select x64 or arm64. Package format, processor architecture, and desktop environment are separate requirements; a successful download doesn't guarantee the package will run on your system. If installation reports dependency errors, start with the package manager's specific message.
System proxy support varies across desktop environments, and some apps still need a proxy address configured separately. First test the local listening port with an app known to support proxies, then decide whether to use another traffic-routing method. Enable features that require extra permissions only after understanding their purpose. Avoid running the entire GUI client with elevated privileges all the time.
Choose a client based on your platform, but check the core to see whether a configuration will work. Similar interfaces and the same subscription don't guarantee identical features.
GUI clientImport · Edit · Start/Stop
↓
Proxy coreHandshake · Transport · Routing
↓
Server configurationProtocol · Address · Security layer
V2Ray grew out of Project V, a modular proxy toolkit. It separates traffic entry points, outbound connections, transport methods, and routing rules, allowing the same core to support different use cases. Server details entered in a GUI are usually converted into a configuration that the core can read. So “V2Ray” can refer to a broader technology ecosystem or to a specific core; it does not simply mean a desktop window or a particular Android app.
For first-time users, the practical benefit of this layered design is easier troubleshooting: check whether the app reaches the local proxy, whether the core starts correctly, and whether the server parameters match. Each issue belongs to a different layer. Identify where the failure occurs before making changes. Reinstalling the GUI won't fix a server-side certificate problem, and changing subscriptions won't resolve a local port conflict.
V2Fly and Xray: Related roots, different feature sets
V2Fly is a community-maintained continuation of V2Ray, while Xray developed as a fork of related code and follows its own feature roadmap. They share some configuration concepts, but their extensions, supported fields, and release schedules don't fully align. Check compatibility against the core you're actually using rather than assuming support because the client name contains similar letters. The technical reference compares protocols and security layers separately to help identify the capabilities your configuration needs.
For example, VMess, VLESS, Trojan, and Shadowsocks are protocol options; WebSocket is a transport method; TLS and REALITY relate to the security layer. These aren't mutually exclusive options in the same category. Seeing a familiar protocol name in a subscription doesn't guarantee the full configuration is compatible. Check the transport, security layer, server name, and related extensions too. Client and server settings need to match; changing the protocol on one side alone usually won't establish a connection.
Three open-source clients, with separately maintained interfaces and cores
v2rayN is a desktop client with GUI controls for server lists, subscription groups, system proxies, and routing. v2rayNG is designed for Android and is primarily used with the Xray core. v2flyNG offers an Android setup path for the V2Fly core. All three are open-source client projects, not server services. After installation, you still need server configuration you're authorized to use. A client’s name also doesn't prove that a subscription source is trustworthy.
Open-source licenses govern how code can be used, modified, and distributed; they don't guarantee connectivity on every network. The GUI, core, and dependencies may each use different licenses, so check the relevant release materials for specific terms. In everyday use, the value of an open-source ecosystem is that its implementation and configuration logic can be discussed, reviewed, and improved—not that a project label proves performance or privacy.
Updates: Keep client upgrades and subscription refreshes separate
Client updates typically cover the interface, configuration generation, dependencies, and bundled core. Subscription updates refresh server entries. They solve different problems. If a protocol feature is missing, check core support and the client's configuration generation. If an address has expired or server settings have changed, check the subscription. Updating a subscription doesn't upgrade the client, and updating the interface doesn't guarantee that custom configurations will adapt automatically.
Back up local settings before updating, and note your current proxy mode and routing rules. After the update, verify the basic connection first, then restore custom DNS, rules, and advanced traffic-routing methods one at a time. If a new error appears, save the specific log and compare settings before and after the update. The download page collects installation links; the home page doesn't list fixed version numbers, keeping client choices separate from short-term release changes.
FIRST-TIME SETUP / QUICK CHECK
Common connection questions
Follow these checks in order when setting up for the first time. Change one setting at a time and test again to keep troubleshooting clues clear.
Why is the server list still empty after installing the client?
A client manages configurations and starts the core; the installer doesn't include server entries. Import a complete share link, or add a subscription URL under subscription group settings and update it. If the list is still empty, check the selected group, URL validity, and response format. A webpage address or explanatory text isn't a share link. See the import steps →
Why are some apps not using the proxy when the client says it's connected?
A connected status usually means the client or core is running; it doesn't mean traffic from every app is being routed through it. On desktop, confirm the system proxy is configured and that the target app follows system settings. On Android, also check whether per-app routing is enabled. Routing only handles traffic that has already reached the core, so changing routing mode alone won't fix a missing traffic entry point. See proxy mode details →
When a connection fails, should you change DNS or the protocol first?
Start with the error stage shown in the logs. A timeout, DNS resolution failure, certificate verification error, and configuration parsing error each call for a different fix. Check the system clock, server address, port, and security-layer settings, then investigate DNS based on the error. The protocol must match the server configuration; changing it at random is not a general-purpose fix. See DNS troubleshooting steps →
Can you copy an entire client configuration when switching devices?
Migrate a subscription or compatible share link first, then configure each device's system proxy, listening address, and routing separately. Desktop environments and Android devices differ in file locations, port usage, and network permissions. Custom JSON may also rely on core-specific fields. Test a basic configuration after migration, then restore complex rules once it works. Check configuration compatibility →
RECENT NOTES / FIELD GUIDES
Setup and troubleshooting notes
Practical tips on platform permissions, subscription updates, and configuration structure. When something goes wrong, save the exact error and check the relevant steps; there's no need to reinstall everything from scratch.
Choose the installer for Apple Silicon or Intel, then follow the system prompts for developer verification, system proxy, and network permissions. Distinguish installation blocks from connection errors so you don't try to fix a local permission issue by changing server settings.
An empty list after a subscription update doesn't necessarily mean the client can't connect. Check URL validity, Base64 encoding, whether updates use the proxy, User-Agent, and group settings. Identify whether the issue is a failed fetch, a parsing error, or entries hidden by list filters.
Follow a generated configuration from logs and DNS through inbounds, outbounds, and routing. Check how tag and outboundTag references connect, and see which outbound each rule affects before editing manually. Don't simply paste configuration snippets together.