Setup BasicsDesktop and Android Client Guides

V2Ray OfficialDownload Clients

Download v2rayN View Guides

Set up subscription imports, then system proxy, followed by routing.

Open sourceMultiple core optionsSetup guides

Five key client settings

Import your connection details first, then choose which apps should use the proxy. The settings below illustrate where to find each option; they are not an interactive client.

Subscription URLs: save once, then update

Subscriptions help manage a set of connection configurations that may change over time. In v2rayN's subscription group settings, enter a remark and the complete URL, save it, then update the subscription. The client fetches the URL's contents and creates the corresponding server entries. Unlike pasting share links one at a time, a subscription gives you a way to fetch updates later. The URL itself is not connection data, though, and saving it alone will not connect you. After updating, check that the group contains valid entries, then select an active configuration. If no entries appear, check whether the URL has expired, whether it returns configuration data, and whether the request is affected by the current proxy settings.

  • Use remarks to identify the source; naming them by purpose can help.
  • Hide the full URL and authentication parameters before sharing screenshots or asking for help.
  • If an update fails, keep the existing configuration and troubleshoot the request path first.
Subscription Group Settings
RemarksDaily subscription
URLhttps://example.com/your-sub

This example URL is for format illustration only. Use a valid subscription you already have.

Update subscription (without proxy)

These five settings solve different problems: subscriptions and share links bring configurations into the client; system proxy and TUN route app traffic through it; routing selects an outbound; and the core handles the connection itself. Troubleshoot in that order rather than changing several switches at once. A successful import means the client can read the configuration, not that the server is reachable. And a webpage loading in your browser doesn't mean other apps are using the same route.

If these concepts are new to you, keep the default settings and start with the smallest workable configuration. Once you can reproduce a stable connection, add domain exceptions or try another connection method. Change one setting at a time and note what happens before and after. For terminology, see the glossary. For platform-specific permissions and installation details, consult the user guides—there's no need to read every parameter before your first launch.

Choose a client for your platform

Use v2rayN on desktop and start by exploring v2rayNG on Android. The download page also helps you choose the right CPU architecture and package type.

Windows

 v2rayN · Desktop / WPF

The desktop edition uses a cross-platform interface, while the WPF edition keeps the classic desktop experience. Before installing for the first time, compare the interfaces and system requirements. There's no need to install both editions for the same subscription. Settings may be in different places, so look for the feature name in the version you're using.

Check your CPU architecture in system information before downloading. After installation, keep the app somewhere easy to manage where it has permission to write files. If it reports a missing runtime, install the required component as described in the setup instructions, then import your subscription.

Go to downloads Windows client →

macOS

 v2rayN · Desktop

Check your chip in About This Mac, then choose the package for Apple Silicon or Intel. The architecture determines whether the app can run directly; it has nothing to do with the protocol used by your subscription.

Follow system prompts to grant app permissions on first launch. Once the system proxy works, consider TUN only if you need it. For network extensions or administrator authorization, follow the platform-specific instructions rather than reusing steps meant for another desktop OS.

Go to downloads macOS client →

Android

 v2rayNG recommended · v2flyNG alternative

v2rayNG uses the Xray core, while v2flyNG offers the V2Fly core. Most modern devices can use the arm64 package. If you're unsure about your device's architecture, check the download page before choosing a universal build. Package architecture and core family are separate considerations.

After importing a subscription, select an active configuration and approve the system VPN prompt when connecting. If the connection drops when the app moves to the background, check battery management and background restrictions. If another networking tool is connected, resolve the conflict over the system connection first.

Go to downloads Android client →

Linux

 v2rayN · deb / rpm

Choose deb or rpm based on your distribution's package manager, then check whether your device is x64 or arm64. Similar-looking GUIs don't guarantee identical desktop environments. Whether apps use the system proxy also depends on the app itself and the desktop session.

First, launch the app and import your subscription as a regular user. Then handle any extra permissions required for TUN. If a webpage and another program behave differently, check each app's proxy settings rather than assuming the desktop proxy applies to every process.

Go to downloads Linux client →

Downloading a client doesn't provide connection settings. Before you start, get a valid subscription URL or share link and make sure you understand where it came from and how it may be used. You can move configurations to another device, but you'll still need to check that device's proxy settings, system permissions, and background access.

View all clients →

Three steps to set up

First confirm the configuration was imported, then check that apps are using the proxy, and finally verify routing. Look for an observable result at each step.

  1. Import a subscription or share link

    First identify what kind of text you have. Add a subscription URL to a subscription group, then update it. Import an individual share link from the clipboard or by scanning a QR code. Don't mistake a documentation URL for a subscription, and don't paste an entire chat transcript into the URL field.

    After the update, check that the group contains configurations and that the remarks look right, then select an entry to use. Leave the transport and security parameters unchanged for now, keeping the full settings supplied by the source. If no entries appear, check the URL and content format before enabling more proxy options.

  2. Choose a connection method

    On desktop, test your browser with automatic system proxy. On Android, approve the system prompt when starting a connection. If a target app has its own proxy settings, check whether it follows the system proxy, uses manual settings, or ignores the system proxy entirely.

    Use TUN only when you have a specific need; it's not required just because you imported a subscription. Check permissions before enabling it, and pause other tools that might take over traffic. LAN sharing is a separate feature and usually isn't needed for a connection on your own device.

  3. Verify the connection and routing

    Start by opening a known reachable site in your usual browser, then check the app that actually needs the proxy. If they behave differently, check how the app connects. If both fail, check the active configuration, system time, and error details in the client logs.

    Once the connection works, try a routing preset and add exceptions one at a time. If behavior changes, revert the last change instead of switching subscriptions, cores, and routing all at once. When you're done, restore any system proxy settings you no longer need so apps don't keep pointing to a local port after the client exits.

If you get stuck, keep the configuration minimal. “Subscription updated,” “core started,” and “browser can connect” are three different checks. Note which step is failing to make troubleshooting easier. Before sharing logs, hide server addresses, user identifiers, and subscription parameters; include only the error details needed.

View the full guide →

Project V and the open-source core ecosystem

Understand the projects, cores, and GUI clients first, then consider updates and compatibility. Similar names don't mean they do the same job.

Project V: from a toolkit to a client ecosystem

Project V is a useful starting point for understanding V2Ray. Its modular network proxy design separates inbound traffic, outbound connections, and routing rules that decide which outbound handles each request. In everyday use, “V2Ray client” often means a GUI management app, not just one executable core. The GUI organizes settings that once required manual editing into forms, menus, and subscription groups, making routine setup easier.

This layered design explains why the same connection details can appear in different clients: share formats exchange configuration, the core handles connections, and the GUI manages settings. Whether specific parameters carry over depends on each side's support for the protocol and extension fields. Understanding the distinction helps narrow down import failures to format issues and startup failures to core parameters, rather than guessing from the client name alone.

V2Fly and Xray: related projects on independent paths

The V2Fly community continues V2Ray-related development, while Xray is another core project that grew from related technical foundations. They share some concepts and protocol foundations, but have developed different features and compatibility ranges. Protocol names listed by a subscription provider are only a starting point: transport methods, security parameters, and implementation requirements matter too. A field accepted by one core may not be accepted the same way by another.

Choose a client and core based on the server's configuration requirements. Don't treat core names as a general performance ranking, or switch tools repeatedly to troubleshoot a single timeout. Check the system time, connection method, and active configuration first, then verify protocol support. This usually makes it easier to compare results and identify the cause.

Open-source licenses: understand the code and usage terms

v2rayN, v2rayNG, and v2flyNG are all open-source clients. Open source means the code can be reviewed, used, and improved under each project's license; it doesn't mean every project uses the same license. The client, its core, and bundled components may each have different terms. If you plan to redistribute or modify them, read the licenses included with the relevant projects rather than relying on the app's name.

A free client doesn't provide connection resources. Subscription URLs, servers, and accounts come from their respective configuration sources; their availability is separate from whether the client code is open source. This site provides download and setup information, not publicly shared subscription credentials. Before use, check that your configuration source is trustworthy and follow applicable local laws and network service terms.

Community maintenance: keep a working setup before updating

The open-source ecosystem relies on the community to fix compatibility issues, refine interfaces, and add features. Client, core, and rule resource updates may happen separately, so check what was updated. After installing a new GUI, review the release notes to confirm whether existing settings can be migrated, whether the same core is still in use, and whether the rule resources remain compatible. Don't skip migration checks just because the interface looks familiar.

Before updating, note your current connection method and routing choices, and back up any necessary settings. After updating, verify the scenarios that already worked before trying new options. Backups may contain subscription and authentication details, so store them as sensitive files. If behavior changes, compare the settings and error messages before deciding whether to roll back. For platform permissions, configuration migration, and common conflicts, see the cross-platform user guides.

Recent technical notes

These articles cover settings, version differences, and errors that are easy to confuse in real-world configurations. Choose one based on the issue you're seeing, then verify the steps in your client.

If you're not sure what to troubleshoot, start with the Getting Started guide and follow the setup steps in order. If your connection already works and you only want to change how specific domains are routed, read the routing guide instead. That way, you won't add extra variables before confirming the basics.

View all articles →