Desktop and Android · Client Setup Guide

V2Ray Clients Download and Setup Guide

Download v2rayN View the guide

From importing subscriptions to configuring routing, follow the actual menus to set up v2rayN and v2rayNG in the right order.

Open source Xray / V2Fly ecosystem Configuration guides

The interface illustrates settings; menu locations and available cores depend on the client. Before sharing a configuration across platforms, check that the core and fields are compatible.

Configuration

Subscriptions, routing, and core settings

First identify where the configuration comes from, where traffic enters, and where requests are routed before changing advanced fields. The graphical client manages settings; the core handles connections using the generated configuration. Each has a distinct role.

Subscription groups and update scope

A subscription URL retrieves a set of server configurations; it is not a single share link. In v2rayN, enter a name and URL under “Subscription Group Settings,” save, then update that group. In v2rayNG, add it under “Subscription Group Settings,” then select “Update subscription.” Create separate groups for different sources to keep updates scoped and avoid mixing manual entries with subscription content. After updating, check the server address, protocol, and transport settings before switching to the active configuration. Subscription URLs may contain access credentials, so hide the full URL in screenshots and troubleshooting notes.

addressportprotocol
See how to import a subscription →

For your first setup, follow one clear path: add a subscription group, select a working configuration, enable a local proxy entry, and test one target app. Once that works, add domain routing, app selections, or custom DNS. Change one type of setting at a time to isolate problems. Changing the core, port, and routing together makes it harder to identify what broke a working setup.

These interface cards illustrate menu concepts; they aren’t a substitute for configuring the actual client. Menu labels may change, so focus on what each setting does: subscriptions retrieve configurations, inbounds accept local requests, outbounds establish connections, and routing selects an outbound. Before editing JSON, read the configuration field reference to identify the relevant section and decide whether you need to leave the graphical interface.

Client downloads

Choose by operating system and device architecture

Use v2rayN on desktop and start with v2rayNG on Android. Installers must also match your device’s processor architecture and system environment. Check your device settings first, then visit the download page for your platform.

Windows

v2rayN offers both a desktop edition and the classic WPF edition. The desktop edition uses a cross-platform interface, while WPF retains the classic desktop layout. Check the system requirements first, then choose the menu layout you prefer. You don’t need to run both editions to import the same subscription.

After the first launch, check the local listening port and system proxy status. An older client still running may already be using the same port; quit it before testing. If your browser has a separate proxy extension, check whether it overrides system settings to avoid conflicts between two proxy entry points.

Go to downloads Windows client

macOS

v2rayN has separate downloads for Apple Silicon and Intel. Check your chip or processor under “About This Mac,” then choose the matching installer. Architecture has nothing to do with interface language, and you can’t reliably identify it from a device’s appearance or purchase year.

After installing, confirm the client launches before setting up a subscription and system proxy. If macOS displays a security warning, check the download source and the specific reason given, then follow the system guidance. Don’t disable security features entirely. Once connected, test proxy behavior in the apps you actually use.

Go to downloads macOS client

Android

v2rayNG uses the Xray core and is the recommended starting point on Android. If you need a configuration for the V2Fly core, see v2flyNG. Most current devices use the arm64 architecture. If you’re unsure, check your device information or the download page’s universal build notes.

On the first connection, approve the system VPN permission. This allows the app to handle network traffic on your device; it doesn’t mean the server connection has succeeded. Once connected, test the target app and check background battery restrictions. If the connection drops when the app moves to the background, check the system’s background-running restrictions before trying another configuration.

Go to downloads Android client

Linux

v2rayN provides deb and rpm packages for x64 and arm64. Choose the package format for your distribution, then select the processor architecture. Package format is unrelated to proxy protocols and does not change server settings in your subscription.

After installation, import your configuration in the graphical client. Support for system proxies varies across desktop environments, and some apps require you to enter a local HTTP or SOCKS address manually. Test browsers, desktop apps, and command-line tools separately: access in one program doesn’t prove that all programs use the same settings.

Go to downloads Linux client

After installing the client, you’ll still need a valid server configuration or subscription. The installer deploys the client; it doesn’t include connection settings you can use right away.

View all clients →

Quick start

Import, choose an entry point, and test the connection

Start with a basic setup you can reproduce, then add custom rules. These three steps follow the full guide; the main difference between desktop and Android is how local traffic enters the client.

  1. Step 1

    Identify the configuration source and import it

    First check whether you have a subscription URL or a single share link beginning with a protocol such as vmess:// or vless://. Add a subscription URL under “Subscription Group Settings,” then update it. For a single share link, use the client’s clipboard import option. Don’t use a webpage URL as a subscription, or enter a subscription URL in the server address field.

    After importing, check that the name, protocol, server address, and port are all present. If a subscription update fails, make sure the URL isn’t truncated or padded with extra spaces, then read the update message. Being able to open the subscription webpage doesn’t mean the client has parsed a valid configuration. Keep the original group while troubleshooting instead of repeatedly deleting and recreating it; you’ll need it for comparison.

  2. Step 2

    Select a configuration and enable a traffic entry point

    On desktop, select a server configuration and enable “Set system proxy automatically.” On Android, select a configuration, tap Connect, and approve the system VPN permission. Start with a clear preset routing mode and avoid adding complex custom rules for now. System proxy settings, VPN traffic capture, and core routing are different layers; similar labels don’t make them interchangeable.

    If you need access to local network services, check the bypass rules and destination address. To restrict which Android apps use the proxy, configure “Per-app proxy” and confirm whether bypass mode is on. Reconnect after making changes and test with requests from the actual app. If other proxy or VPN tools are running on the device, quit them before testing.

  3. Step 3

    Test with real requests and logs

    A connection button showing that the client is running only confirms that it has started. Next, open a website or app you actually use, check whether the request succeeds, and review the logs for outbound, DNS, or handshake messages. Built-in speed tests can help compare connections under current conditions, but they don’t represent sustained download speeds or replace testing access in the target app.

    When something fails, check in this order: local entry point, DNS, server connection, then destination service. Note the mode you selected and the changes you made; adjust one variable at a time. If a browser works but another app doesn’t, check that app’s proxy settings first. If all requests fail, check the configuration, system time, and server reachability instead of piling on routing rules.

To reset, disconnect first and restore the system proxy, then select a configuration again. Keep a working basic setup so you can pinpoint problems caused by later rule changes.

Read the full guide →

Open-source ecosystem

How clients, cores, and configurations fit together

V2Ray is the broader ecosystem and technical context; v2rayN, v2rayNG, and v2flyNG are specific client names. Knowing the difference between the interface and the core helps you figure out where a setting takes effect.

From Project V to the core ecosystem

Project V focuses on modular network proxying, with V2Ray as one widely used implementation. V2Fly continues community maintenance of V2Ray, while Xray has developed its own implementation and features within the related code and technology ecosystem. They share some concepts and configuration conventions, but project names alone don’t guarantee full compatibility. Support for a protocol doesn’t mean every transport option, security field, and routing resource can be used interchangeably.

Graphical clients manage subscriptions, edit configurations, control startup, and integrate with the system. The core performs the actual network processing. When you see an option in a menu, check both how the client saves it and whether the active core recognizes the corresponding field. Manual edits to files generated at runtime may be overwritten the next time you save settings; make lasting changes through a configuration option supported by the client.

Open-source licensing for the three clients

v2rayN, v2rayNG, and v2flyNG are all open-source clients, with graphical workflows designed for desktop or Android use. The v2rayN and v2rayNG projects use GPL-family licenses, while v2flyNG uses GPLv3. Refer to each project’s license text for the exact terms, third-party components, and distribution conditions. The V2Fly and Xray cores use the MPL 2.0 license. A client and a core are separate software packages, so the license for one does not automatically apply to every component.

Open source means code can be read, studied, and maintained under the applicable license; it doesn’t mean installers from every source are equivalent. Choose a client based on your platform, required protocols, and configuration compatibility. For desktop, start with v2rayN. On Android, use v2rayNG for Xray configurations; consider v2flyNG when you need V2Fly-specific behavior. The client doesn’t determine how a server is operated or tell you whether a subscription source is trustworthy.

Keep a reproducible setup before updating

Client interfaces, core capabilities, and rule resources may be updated separately. After an interface update, check which core is active. After updating rule files, confirm that custom tags still point to the right resources. Before updating, note the local port, system proxy mode, active configuration, and custom routes; if export is available, save a controlled backup. After updating, test a request that used to work, then restore advanced settings one at a time. This makes it easier to avoid conflating multiple changes with one failure.

Subscription updates and software updates are different. The first refreshes server configurations and may change addresses, protocols, or connection settings; the second changes the client or its components. A single configuration from a subscription usually can’t represent all routing preferences on a device, and local client rules aren’t automatically shared with other devices. When managing multiple devices, note which settings come from subscriptions and which are local to avoid confusion during migration.

JSON reference and protecting sensitive information

For more advanced configuration, start by reading the four sections inbounds, outbounds, routing, and dns. Limit inbound listeners to what you actually need, make sure outbound tags match routing references, and consider DNS behavior alongside your domain rules. The example geosite:cn rule requires the corresponding resource. Copying the rule without making the resource file available may prevent the configuration from starting as expected.

Full configurations, share links, and subscription URLs may contain credentials. When asking for help, include only the necessary fields, hide credentials and the full subscription path, and specify the client, active core, stage of failure, and relevant logs. Destination domains in logs can also reveal browsing activity, so share only the excerpts needed to troubleshoot. This makes problems easier to reproduce than a screenshot of a failed connection alone.

Continue to the V2Ray configuration reference →

Configuration guides

Share links, router deployment, and speed troubleshooting

Go beyond imports to gateway deployment and layered troubleshooting. These three recent articles cover different scopes; choose the one that fits your issue instead of changing everything at once.

Getting Started

vmess:// and vless:// share links vs. subscription URLs: differences and import instructions

A single share link stores the settings for one connection; a subscription URL retrieves and updates a set of configurations. This article explains how their import options, update scopes, and storage differ, with steps for v2rayN and v2rayNG. Useful if a copied link isn’t recognized, you chose the wrong import option, or configurations changed after an update.

Read the import guide →
Platform Setup

Running the Xray core on a router or secondary gateway: deployment overview and configuration essentials

Running a core on your main router and using a secondary router as a gateway are different network setups. This article explains how device gateways, transparent proxying, and DNS routing fit together, and what forwarding paths and rollback options to check before deployment. It’s a deployment overview—not a reason to treat a desktop client’s system proxy toggle as network-wide traffic capture.

Read the deployment guide →
Troubleshooting

Troubleshooting slow V2Ray connections: isolate nodes, network paths, and local settings

Slow speeds can result from server load, network paths, local settings, or the destination service. This article walks through checks at each layer and distinguishes connection latency, sustained throughput, and app responsiveness. Keep test conditions consistent and compare one variable at a time; repeatedly switching configurations based on a single speed test won’t reveal the bottleneck.

Read the troubleshooting guide →

Troubleshooting a system proxy or connection logs? The article directory also covers routing modes and error messages. Browse by issue to find the next step.

View all articles →
V2Ray Client Downloads