Desktop Client Setup Guide

V2Ray Config Guide Import v2rayN Subscriptions and Configure Routing

From importing subscriptions to routing traffic, follow your client’s menus, then check the runtime logs to see where traffic goes.

  • VMess
  • VLESS
  • Trojan
  • REALITY

Client Downloads

Platforms and Packages

Choose your platform, then check the processor architecture. The download page lists the system requirements for each package.

Windows

v2rayN is the recommended desktop client. The Desktop and Classic WPF editions are two interfaces for the same client: choose Desktop for a consistent cross-platform experience, or Classic WPF if you prefer the older interface. Before downloading, go to Settings → System → About to check your system type and confirm that your device matches an architecture listed on the download page.

When upgrading from an older version, back up your settings using the client’s built-in method. If the old program is still running in the system tray, exit it before launching the new one. Running both at once can cause them to compete for the local proxy port. If startup fails, check the port before deleting your subscriptions and starting over. After migrating, confirm that the system proxy points to a port the new program is listening on.

Go to Downloads

macOS

Check your processor under About This Mac. Choose the Apple Silicon package for an Apple chip or the Intel package for an Intel processor; don’t guess based on the computer’s appearance or purchase date. Open the disk image and follow the installer prompts to move v2rayN to Applications, then launch it from there.

If an app suddenly bypasses the proxy after you switch between Wi-Fi and Ethernet, check the proxy settings for the active network service before reinstalling anything. Keep settings separate on shared computers, and don’t leave exported files containing subscription URLs in public folders. If the system asks for permission, check which app and action the prompt refers to before granting access.

Go to Downloads

Android

For the Xray core, start with v2rayNG. If your configuration specifically requires the V2Fly core, choose v2flyNG. If your device supports arm64, you can use the matching package; if you’re unsure which app architecture your device uses, choose the universal package. The first time you connect, the system will prompt you to authorize VPN access. Importing a server list alone does not start the VPN service.

If the connection drops only after the screen locks, check the app’s background restrictions before investigating the network or server. If another app is already using the VPN service, stop it and test the new setup on its own. If only one app can’t connect, check whether it’s included or excluded in the per-app proxy list. Other apps working doesn’t mean this one is covered.

Go to Downloads

Linux

v2rayN provides separate downloads by package format and processor architecture. For Debian or Ubuntu, choose the deb package; for Fedora and other RPM-based distributions, choose rpm. Confirm whether your system is x64 or arm64 before selecting a file. A compatible package format doesn’t guarantee that all runtime dependencies are installed.

Desktop apps, terminal programs, and browsers may not use the same proxy settings. If the desktop can connect but a terminal can’t, check where that terminal gets its proxy settings. If the installer reports missing dependencies, save the exact message and check your distribution’s requirements instead of repeatedly downloading packages for other architectures. If you need TUN, also check virtual network adapter permissions and existing routes.

Go to Downloads
View All Clients

How the Configuration Fits Together

Subscriptions, Routing, and Traffic Capture

Read the diagram on the left in configuration order; it doesn’t show packet flow. Set up your servers and routing first, then choose how app traffic reaches the client. When troubleshooting, check each layer separately so a failed subscription update, a server handshake failure, and an app bypassing the proxy don’t get mistaken for the same problem.

v2rayN · Configuration Order

  1. Subscription Group Add a Subscription Group
  2. Server Node Set as Active Server
  3. Routing Rules Routing Settings
  4. Outbound / Direct outboundTag
  5. System Proxy / TUN Set Up System Proxy Automatically · Enable TUN Mode

Subscription groups determine where your server nodes come from and which ones get updated. In v2rayN, open Subscription Groups → Add a subscription group, enter a label and subscription URL, and save. Then select Update all subscriptions and check that nodes appear in the group. In v2rayNG, add the URL under Subscription group settings, return to the main list, and update it. Saving the URL and downloading the list are separate steps. If the list is empty, check the update message, URL validity, and response format. Never paste a subscription URL into a public log.

Getting Started

Quick Start: Import, Connect, and Test

  1. Import a Subscription and Check Its Source

    Get the subscription URL or a single-server share link from your provider. They serve different purposes: add a subscription URL under Subscription Groups to fetch and update a list of servers; import a single-server link through the server import option instead. If you’re given a subscription management webpage, copy the client subscription URL from its interface. Don’t use the login page address from your browser’s address bar.

    After saving a subscription group in v2rayN, update it and open the new group to check for server nodes. If you have several groups, label the new one so its source is easy to identify, and check the protocol used by its nodes. If the old list still appears after an update, first confirm that the update actually succeeded; don’t rely on server names. If it failed, read whether the error concerns downloading, authentication, or parsing, then check that part of the process. Subscription URLs may contain access credentials, so hide the entire URL in screenshots and support requests.

  2. Set an Active Server and Choose How to Route Traffic

    Choose a node supported by your client’s core. In v2rayN, set it as the active server, then select System Proxy → Set up system proxy automatically from the system tray. Start testing with a browser that follows system proxy settings. Running the client doesn’t mean the browser is using the proxy; if it has a proxy extension, check whether that overrides system settings. Don’t switch nodes, change DNS, and enable TUN in the same test. Even if the connection improves, you won’t know which change made the difference.

    In v2rayNG, select a node on the main screen and start the connection, then grant VPN permission when prompted. For the first test, leave the per-app list unchanged. Once the basic connection works, choose which apps to include or exclude. If a desktop app doesn’t use system proxy settings, check whether it lets you enter a local proxy manually. If you need TUN, check the installation guide for your platform’s permission and routing requirements.

  3. Retest the Same Destination to Find the Failure

    In the same app, visit a destination that should use the proxy, then check routing with one that should connect directly. Change one setting at a time and note when you retry so you can match it to the runtime logs. A lit icon only means the service has started, and a successful latency test doesn’t prove that the app’s request used the right outbound. If the browser has cached content, test with a fresh request; a page that’s still visible doesn’t mean the connection works.

    If there’s no matching inbound in the logs, check the app’s proxy settings and local listening port. If traffic arrives but takes the direct route, check rule order and destination match conditions. If the proxy outbound is selected but the handshake fails, check the server parameters, network connectivity, and system time. To undo a change, revert the most recent setting and compare again; you don’t need to clear the entire client. Before you finish testing, restore the previous log level to avoid accumulating excessive connection records during everyday use.

View the Full Guide

Open-Source Ecosystem

Project V, V2Fly, and Xray

Project V: How the Client and Core Work Together

The early Project V used V2Ray as its core for handling network proxying. The core listens for local connections, matches routing rules, and establishes outbound connections. The graphical client provides an interface for managing subscriptions, server lists, and common settings. This division of responsibilities continues today: update a subscription group or switch the active server in the client, and it generates the configuration the core needs—no need to edit the entire file by hand every time.

In everyday conversation, “install V2Ray” might mean installing a client or configuring a core. Know which one you mean before following a guide. If you can’t find a menu, check the client and interface version. If the core won’t start, look at the specific configuration fields and runtime logs. These issues call for different troubleshooting steps; a similar-looking interface doesn’t mean the same setup instructions will apply.

V2Fly and Xray: Related Projects with Different Paths

V2Fly is a community-maintained continuation of the V2Ray core. Xray evolved from V2Ray code and developed into a separate core family. They share some protocols and configuration concepts, but their supported transports, security options, and fields aren’t identical. v2rayN can use different cores depending on the configuration, but that doesn’t mean every server can be switched freely between them. For mobile clients, start with the requirements of your existing servers rather than comparing interfaces alone.

For example, if your provider specifically requires REALITY or XTLS Vision flow control, first confirm that your chosen core and client support those features. Then check the server protocol, transport, and security settings. Simply switching cores while keeping incompatible parameters may leave a server visible in the list but unable to connect. For a side-by-side feature comparison, see our three-client comparison.

What’s Open Source: Interfaces, Cores, and Configuration Formats

v2rayN, v2rayNG, and v2flyNG are all open-source graphical clients. v2rayN is for desktop, v2rayNG uses the Xray core, and v2flyNG is an Android alternative based on the V2Fly core. Clients and cores are maintained separately, and bundled components may have their own open-source licenses; check the license information for the specific package. Open source describes the code and distribution terms, not how third-party subscription services or servers are operated.

VMess, VLESS, and Trojan are proxy protocols that servers may use. REALITY is a security mechanism in the Xray ecosystem, not a proxy protocol on the same level as those three. When reading server details, distinguish the protocol, transport, and security settings, then check which ones the core supports. To find out whether a field is entered by the client or interpreted by the core, start with the quick reference.

Updates: Keep Client Updates Separate from Subscription Updates

Updating the package replaces the client program and may also change the core, dependencies, or interface. Updating a subscription fetches the latest server list from your provider. If an older server disappears after an update, check whether the provider removed it and whether you need to select a new active server. If the interface still opens after migrating an old configuration but the core won’t start, check whether the parameters used to generate its configuration are still supported.

Before upgrading, note your main settings and proxy mode, and back up anything you want to keep using the client’s built-in method. After upgrading, retest with an existing server to make sure the program works before changing your rules. Don’t rewrite traffic routing while migrating. If the guide’s interface doesn’t match yours, rely on the messages, core logs, and system requirements. Compare installation steps and common limitations by platform in the complete installation guide.

More to Read

Client Setup Articles

v2rayNG on Android: VPN Service Permissions, Battery Settings, and Per-App Proxy

Learn how v2rayNG requests VPN service permission, how to configure battery optimization exceptions on different Android devices, and how to use include and exclude modes for per-app proxying.

For anyone who can connect but loses the connection after locking the screen, or finds that only some apps aren’t using the proxy as expected. These symptoms have different causes, so identify which one you’re seeing before changing settings.

REALITY and XTLS Vision Explained: Handshake Camouflage and Faster Flow Control

A plain-language explanation of REALITY’s handshake camouflage and how XTLS Vision flow control reduces redundant encryption, including how they work together in the Xray core.

Start with the client settings to understand the different roles of security and flow control—and why a successful import still requires checking core support.

V2Ray Connected but No Internet? A Step-by-Step Troubleshooting Checklist

Check system proxy settings, local ports, server time, DNS, routing rules, and TUN conflicts in order to find out why V2Ray says it’s connected but you can’t browse.

Choose a test destination that reliably reproduces the issue. First confirm whether the app’s request reaches the client, then check routing and the handshake. Avoid switching servers back and forth for the same problem.

View All Articles
V2Ray Client Downloads