v2rayN Usage Guide · Downloads & Setup

Download v2rayN Subscription Setup & Proxy Settings

Follow the actual settings to add a subscription, then configure the system proxy and routing for your needs.

GPL-3.0 open-source license

Get Started in Three Steps

  1. Add a subscription
  2. Select a server
  3. Enable the system proxy

Static interface illustration. Menus and options may move as the client is updated.

Proxy Settings: Know the Four Options

Routing, system proxy, core type, and subscription setup each handle a different part of the process. Identify which layer is causing the issue before changing its settings.

Routing

Routing rules determine whether connections passed to the core go direct, through a proxy, or get blocked. For everyday use, start by learning the “Bypass mainland China” preset: connections matching mainland Chinese domains or IP addresses go direct, while others follow the rules. “Global” sends all connections handled by that route through the proxy. Neither option replaces the system proxy or means every app is covered. After switching, test the same site again and avoid changing DNS and servers at the same time. With custom rules, check their order: an earlier match can prevent later rules from taking effect.

Routing Presets
Bypass mainland China
Global
View routing settings →

Core Type

v2rayN manages the interface and configuration; the core handles the actual connections. Choose a core that supports the server’s protocol, transport, and related parameters—not just one with a familiar name. Xray and sing-box are separate implementations with different configuration fields and support. Start with the client’s compatible defaults, then check the logs if a field isn’t supported. V2Fly is another core family and should not be confused with sing-box. After changing cores, verify that the server starts successfully rather than relying on its continued presence in the list.

Core Types · Switching Explained

Check the configuration against Xray’s protocol support and logs; parameters such as REALITY must match the server.

Core and protocol terminology →

System Proxy

On desktop, selecting “Set system proxy automatically” adds the local proxy endpoint to the operating system’s proxy settings for apps that follow them. “Clear system proxy” removes that setting; “Leave system proxy unchanged” keeps its current state—it does not disconnect the proxy. If a browser works but another app does not, check whether that app uses the system proxy or has its own proxy address configured. System proxy and TUN are different ways to route traffic. For your first setup, start with the system proxy and explore other modes only after confirming the basic connection works.

System Proxy
Clear system proxy
Set system proxy automatically
Leave system proxy unchanged
Troubleshoot proxy issues →

Import on Android

The plus menu in the top-right corner of v2rayNG offers “Import from clipboard” and “Scan QR code.” These options are commonly used to add a single server’s share link; don’t treat a share link as a subscription that can be refreshed regularly. For a subscription URL, open “Subscription groups,” enter a remark and the address, save, then update the subscription. After importing, select a configuration and start the connection. Approve the system VPN prompt the first time. QR codes and clipboard contents may include access credentials, so hide addresses, identifiers, keys, and other sensitive fields before sharing screenshots.

v2rayNG +
Import from clipboard
Scan QR code
Compare subscription options on both clients →

Client Downloads: Choose by Operating System

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

Windows

Choose v2rayN. The download page distinguishes the Desktop edition from the classic WPF edition: Desktop uses a cross-platform interface, while WPF retains the classic desktop workflow. Check the listed operating system and runtime requirements rather than relying on the filename alone. Extract the archive fully to a writable folder before running it; don’t launch the app from inside the archive.

Go to downloads Windows client

macOS

Choose v2rayN and check your chip under “About This Mac.” Apple Silicon uses arm64; Intel uses x64. If macOS shows a security warning the first time you open the app, verify the download source and installation steps, then use the option provided by the system. Don’t disable system-wide security protections just to run the client.

Go to downloads macOS client

Android

Start with v2rayNG, which uses the Xray core; choose v2flyNG if you need the V2Fly core. For most modern devices, check whether the architecture is arm64. If you’re unsure, see the universal-build notes on the download page. Starting a connection requires system VPN permission. If another VPN is already connected, resolve the conflict first, then check the server and per-app proxy settings.

Go to downloads Android client

Linux

Choose the v2rayN deb or rpm package that matches your x64 or arm64 architecture. deb packages are commonly used on Debian and Ubuntu; rpm packages are common on Fedora and similar distributions. Desktop environments differ in how they support system proxy settings, so a successful installation doesn’t guarantee apps are using the proxy. If needed, enter the local proxy endpoint in the app’s own network settings.

Go to downloads Linux client

First-Time Setup: Follow These Steps

Installing the client is just the first step. You also need a valid configuration, a working proxy endpoint, and the right way to route traffic. The steps below focus on desktop; mobile instructions are covered separately.

  1. Add and Update a Subscription

    In v2rayN, open “Subscription Group Settings,” add a group, enter a recognizable remark, and paste the full subscription URL into “Address (URL).” For your first setup, keep the default update options, save, then update the group’s subscription. A subscription URL typically returns a set of configurations. It serves a different purpose from a single-server share link beginning with vmess:// or vless://; don’t interchange their import options.

    In v2rayNG, manage subscriptions from “Subscription groups.” If the list is still empty after an update, check the logs for download or parsing errors. Make sure the URL was copied with all query parameters and isn’t a link to an information page. Subscriptions are sensitive: when troubleshooting, note only the error type and never post the full URL publicly.

  2. Select a Server and Routing Mode

    After updating, select a configuration in the intended group and set it as the active server. First confirm that the current core can recognize it, then choose a routing preset for everyday use. Beginners can start by learning what “Bypass mainland China” does, and briefly switch to “Global” to compare routing behavior if needed. Change one setting at a time and keep the test conditions reproducible.

    Importing a configuration doesn’t guarantee the server is reachable, and the client can’t create connection details for you. A timeout could be caused by the service, address, port, or current network; one test alone can’t identify the cause. If the logs say a protocol parameter isn’t supported, check the core and configuration instead of repeatedly updating the same subscription.

  3. Enable the Proxy and Test It

    On desktop, select “Set system proxy automatically,” then use a browser that follows the system proxy to visit the target site while checking the client logs. On Android, select a configuration, start the connection, and approve the system VPN prompt. When testing, distinguish DNS resolution failures, connection timeouts, and certificate errors; each calls for different checks.

    Then test a site that normally works to make sure routing hasn’t disrupted your usual connection. Before closing the desktop client, clear the system proxy so it doesn’t keep pointing to a local port that is no longer running. If the browser works but other apps don’t, check their proxy settings first. If all connections fail, check the core startup logs and local port.

Open-Source Ecosystem: Clients vs. Cores

Projects with similar names don’t necessarily do the same job. Knowing what each layer does helps avoid mistakes when choosing, updating, and troubleshooting software.

Project V and Core Families

Project V provides context for understanding the V2Ray ecosystem. The V2Ray core provides foundational capabilities such as protocol handling, inbound and outbound connections, and routing. V2Fly continues community maintenance of related cores, while Xray is another implementation that grew out of this technical ecosystem. They share a background but have evolved differently and use different configurations.

VMess, VLESS, and Trojan are protocol-related names; WebSocket and gRPC describe transport methods; REALITY involves connection security and handshaking. These terms belong to different layers and aren’t interchangeable options. Choose the combination supported by the server, then confirm the client’s core can handle it.

Three GUI Clients

v2rayN gives desktop users an interface for managing subscriptions, selecting configurations, and setting up the system proxy and routing. v2rayNG is for Android and uses the Xray core. v2flyNG is also for Android, offering an alternative for users who need the V2Fly core. Similar interfaces don’t guarantee the same parameter support—that depends on the core each client includes.

All three clients are open-source projects released under the GPL-3.0 license. Open-source licenses set the terms for using and distributing code; they don’t mean every dependency uses the same license. When following configuration instructions, check both the client and core names. Menu locations in one client may not match another.

Subscriptions and Connection Services

The client stores and runs configurations, subscriptions provide configurations, and servers provide the actual connection endpoint. Each has a different role. This site offers client selection and setup instructions; it does not provide subscription URLs or maintain servers. If the list is empty after installation, first obtain a configuration from a legitimate source rather than looking for a subscription option in the system proxy settings.

Updating a subscription fetches the latest content published by the server, and may overwrite manually edited servers. Before keeping a test configuration, check how groups and copying work in your client. A subscription may also stop working because its URL changed or access was revoked; reinstalling the client repeatedly won’t fix every issue.

Update and Troubleshooting Order

Updating the client, core, and subscription are three separate tasks. A client update may change the interface and how configurations are generated; a core update affects connection capabilities; a subscription update changes the configurations themselves. If compatibility issues arise, note the error and steps taken, then decide which layer needs an update. Avoid making several changes at once, or the issue may become impossible to reproduce.

Before updating, keep any groups and custom rules you need. Afterward, test a configuration that worked before. If it fails, check in order: whether the core starts, whether the server is reachable, whether DNS works, and whether the app uses the proxy. Before sharing diagnostics, remove subscription URLs, user IDs, keys, personal paths, and other sensitive details.

Configuration Guides: Browse by Topic

These three recent guides cover first-time installation, DNS routing, and share links. Get a basic connection working first, then explore additional settings as needed.