Client Downloads · Setup Guides

V2Ray Client Guide Downloads & Setup

Download v2rayN Browse Guides

From subscription imports to routing rules, follow the actual menus to configure the proxy and check connections in order.

  • VMess
  • VLESS
  • Trojan
  • Shadowsocks

Getting Started

V2Ray Quick Start

Import a valid configuration first, then check whether traffic reaches the client. Installation, server subscriptions, and the system proxy are separate steps. Follow them in order to give troubleshooting a clear starting point.

Setup & Import

Add a Subscription Group

The client manages configurations; it does not create usable servers when installed. Start with a subscription URL from a known source that is still valid. Subscription URLs often contain account identifiers, so copy the full address and don't mistake a provider's web dashboard URL for a subscription link.

In v2rayN, open Subscription Group > Subscription Group Settings from the top menu. Add a group and its URL, save, then select Update Current Subscription (without proxy). If your network cannot reach the subscription service directly, try updating through an existing working proxy. Check the log afterward to confirm that servers appear in the list. If the update fails, check the URL and response before considering a reinstall.

Servers & Modes

Select an Active Server

Choose a server in the list, then right-click and select Set as active server. Server names are labels, not proof that a protocol is suitable. After importing, check that the address, port, and transport settings are intact, then run Test server real connection delay to see whether the proxy handshake completes.

For an initial test, keep the default routing rules and avoid adding complexity. At the bottom of the main window, set System Proxy to Automatically configure system proxy, then check the Routing option. The system proxy directs apps that honor system settings to the local proxy; routing rules determine where traffic goes after reaching the core. These settings are not interchangeable.

Connect & Verify

Check the Connection in Use

Open the webpage you want to test and watch the v2rayN log at the bottom of the window. A matching connection entry confirms that the app's request reached the client. A page loading in your browser does not mean every app uses the proxy: some apps have their own proxy settings, while others read system settings only at launch.

If the page still won't load, check the system clock, active server, local listening port, TLS settings, and routing rules one at a time. Before exiting the client, clear the system proxy so the system doesn't point to a closed local port. In v2rayNG on Android, also check the system's VPN connection permission and background activity; desktop tray-menu steps do not apply.

Read the Full Guide → Setup Guides by Platform

Platforms & Clients

V2Ray Downloads

Use v2rayN on desktop. On Android, v2rayNG with the Xray core is the usual choice; choose v2flyNG if you need the V2Fly core. The download page lists package formats, processor architectures, and client differences. Choose your operating system first, then the right package.

Windows

v2rayN · Desktop / Classic WPF

For a new installation, consider the desktop edition with its cross-platform interface. If you prefer the classic layout, choose the WPF edition. Menus may differ between the two, but Subscription Group, System Proxy, and Routing still refer to subscription management, app traffic entry, and core-level routing. Don't judge whether a setting is active by button appearance alone.

Before installing, check your system type under Settings → System → About and read the download page's compatibility notes. After launch, test the standard system proxy before considering TUN for app-specific needs. Features that require elevated privileges follow a different troubleshooting path from the regular proxy. If something fails, check the log and avoid changing multiple switches at once.

Go to Downloads

macOS

v2rayN · Apple Silicon / Intel

In About This Mac, check the Chip or Processor entry and choose the matching architecture. Apple Silicon and Intel have different download options; the same package format does not make them interchangeable. Complete the first launch and grant system permissions before importing a subscription, then confirm that the client window and log display correctly.

Check the system proxy under System Settings → Network → Current network service → Details → Proxies. If webpages stop loading after you exit the client, first check whether the proxy still points to a local listening address. After switching between Wi-Fi, Ethernet, or other network services, check the service currently in use—not just the one you used before.

Go to Downloads

Android

v2rayNG · Xray / v2flyNG · V2Fly

Most recent phones can use the arm64 package. If you're unsure about the architecture, check the universal build notes. The main difference between v2rayNG and v2flyNG is the core they use and the configurations it supports. Similar-looking interfaces don't guarantee compatibility with every protocol or transport setting. Check your subscription requirements before choosing an alternative client.

In v2rayNG, open Subscription Group Settings from the top-right menu, add a subscription, then return to update the server list. On the first connection attempt, Android asks for VPN permission. This allows the app to route local traffic; it does not confirm that the remote server is reachable. If the connection drops when the screen locks, check battery optimization and background activity permissions in the system app settings.

Go to Downloads

Linux

v2rayN · deb / rpm · x64 / arm64

First identify your distribution's package format, then check the processor architecture. deb and rpm belong to different package management systems; x64 and arm64 refer to different hardware. Choose from the four combinations based on both, not just the file extension. Install and launch through your distribution's software installer; check the download page for desktop environment dependencies.

Whether Linux apps use the system proxy depends on the desktop environment and each app's implementation. Browsers may follow system settings, while terminal programs and background services may need separate configuration. Test with an app that explicitly supports proxy settings, confirm the local proxy works, then check other programs. An app that isn't using the proxy does not mean the subscription import failed.

Go to Downloads

When migrating a configuration, move the servers first, then check local settings. You can reuse a subscription URL across devices, but listening ports, system proxy status, permissions, and routing choices usually depend on each device's environment. Share links and QR codes may contain identifying details; check who will receive them before sharing. In public discussions, include only settings relevant to the issue.

View All Clients → Compare the Three Clients →

Configuration Walkthrough

Subscriptions, Routing & Cores

Subscriptions determine which servers are available, routing determines where requests go, and the core handles protocol execution. Keep these three layers separate to narrow down a problem. The client generates the runtime configuration; a share link is not a complete configuration file that the core can read directly.

Update Subscriptions & Import Servers

A subscription URL provides a list of servers; a share link usually describes just one. In v2rayN, enter the URL under Subscription Group Settings, save, and update the relevant group. If the list doesn't change, check the update log to distinguish a network request failure from an unrecognized response or an expired subscription. A traditional VMess share link encodes server fields after the protocol prefix. It is not native core JSON: the client must parse it, so you can't paste it directly into the core's runtime configuration.

  • Check the group before updating to avoid overwriting servers you've edited manually.
  • Subscription URLs and share links may contain identifying information.

v2rayN · Menus & Data Formats

Subscription Group
  Subscription Group Settings
  Update Current Subscription (without proxy)
  Update Current Subscription (through proxy)

Traditional VMess Share Link Structure
vmess:// + Base64(JSON)

Common Fields After Decoding
add  → Server address
port → Server port
id   → User ID
net  → Transport
tls  → Transport security settings

DNS also needs to be checked layer by layer. System DNS, a browser's secure DNS, and the core's DNS settings may use different paths. Changing system DNS may not affect how the core resolves names; changing core DNS may not affect apps that bypass the proxy. Note which app made the request and how its traffic is handled, then adjust the relevant setting. This is easier to reproduce than changing every DNS server at once. See V2Ray DNS Settings for details.

Project V · V2Fly · Xray

The V2Ray Open-Source Ecosystem

Clients, cores, and server providers play different roles. Open-source licensing describes how code can be used and developed; whether a connection works depends on the configuration, remote service, and current network. A client's name alone says nothing about connectivity.

Project V & Core Families

V2Ray is part of the Project V proxy ecosystem, built around separate configuration for inbound and outbound connections, routing, and transport modules. V2Fly continues V2Ray's community development, while Xray has developed from related code into a separate core. They share concepts and some configuration fields, but that doesn't mean every new feature works the same way. When following a guide, check both the client and the core actually in use: “V2Ray configuration” alone doesn't define the compatibility scope.

VMess, VLESS, Trojan, and Shadowsocks are protocols. TCP and WebSocket are transport options, while TLS covers transport security. These belong to different layers, not one group of interchangeable options. If the server address is correct but the connection still fails, check the port, protocol credentials, transport path, and server name—not just the server label.

What Each Desktop Client Does

v2rayN is for desktop platforms, with an interface for subscription management, server lists, logs, system proxy, and routing. v2rayNG is for Android and uses the Xray core; v2flyNG is an Android option based on the V2Fly core. All three are open-source software for local configuration management and connection control. They don't provide remote servers, and installing them doesn't give you a usable subscription automatically.

Desktop and phone clients can use subscriptions from the same source, but system permissions, traffic handling, and background activity work differently. Desktop tray instructions don't apply to phones, and a phone's connection permission doesn't replace the desktop system proxy setting. To use a subscription across devices, sync the subscription source first, then check each device's runtime settings separately.

Open-Source Licenses & Configuration Boundaries

The v2rayN, v2rayNG, and v2flyNG client projects use the GPL-3.0 license; the V2Fly and Xray core code uses the MPL-2.0 license. Check each project's license notices for specific files and included dependencies. Open-source licenses govern the use, modification, and redistribution of code; they don't guarantee that remote servers are available. A free client also doesn't mean every third-party subscription is free or will remain valid.

Subscription URLs, user IDs, and authentication fields may be linked to personal accounts. Share complete configurations only with trusted devices, and remove sensitive details from public logs. When asking for help, include the error type, protocol, and necessary settings; don't post a full subscription URL or node QR code just to describe a problem.

Updates & Troubleshooting

Client, core, subscription, and routing data updates each change different things. A client update may change the interface or how configurations are generated; a core update affects protocol implementation; a subscription update fetches remote servers; and a routing data update changes domain or address lists. Updating one doesn't refresh the others. Before troubleshooting, note what you just changed to help identify which layer is responsible.

When something goes wrong, preserve the smallest configuration that reproduces the issue, check the system clock and local port, then review TLS, routing, and DNS. Don't switch servers, change cores, and enable TUN all in one test. For menu instructions by platform, use the cross-platform guide. For a specific concept, check the FAQ first, then return to the steps you're following.

  • Project V
  • V2Fly core
  • Xray core
  • GPL-3.0 / MPL-2.0
Read the Cross-Platform Guide Browse FAQs →

Setup Notes

Recent Guides & Troubleshooting

Once your first connection works, move on to speed tests, syncing across devices, and intermittent timeouts. Identify which layer an article covers before changing settings. An open port doesn't prove the proxy works, and identical configurations don't mean network conditions are the same.

Browse All Articles →