Desktop Clients · JSON Configuration Guide

V2Ray Desktopv2rayN Client Downloads

Download v2rayN View Guides

Find open-source client downloads, subscription import steps, and routing configuration fields. Choose your OS first, then check the core and configuration format.

  • Protocol
  • VMess
  • VLESS
  • Trojan
  • Shadowsocks

01 / CLIENTS

Choose a V2Ray Client by Platform

Use v2rayN on desktop and consider v2rayNG on Android. Check package architecture, interface type, and core support separately.

The client stores server profiles, updates subscriptions, and generates runtime configuration. The core handles protocol handshakes, routing, and connections. After installing the client, import valid connection details from your service provider. The software does not include working servers, and a subscription URL is not an installer. For your first connection, keep the default listening settings and test with a known-good configuration. Then adjust routing and DNS one setting at a time to make the effects easier to trace.

Windows

v2rayN · Recommended

The download page offers v2rayN Desktop and the classic WPF edition. Desktop uses a cross-platform interface, while WPF retains the classic desktop experience. Both rely on the selected core and server settings; choosing an interface does not mean both editions support exactly the same protocols. Check your system architecture before choosing an installer, and don't judge an installer's purpose by its file size alone.

After installing and launching the app, import a subscription or a single share link, select a server, and enable the system proxy. Browsers usually follow system proxy settings, but command-line tools, games, and some background apps may use their own network configuration. If a browser connects but another app doesn't, first check whether that app honors the system proxy instead of repeatedly switching servers. Cross-check port conflicts, core status, and proxy mode in the logs and settings.

Download for Windows

macOS

v2rayN · Desktop

Check your chip under About This Mac: Apple Silicon uses arm64, while Intel uses x64. The download page lists packages for both. The client interface and system network settings are separate layers. Opening the main window only confirms that the app has launched. Also check that the core is running, the local listening port is open, and the app you're testing uses the right proxy endpoint.

When importing an existing configuration, check that the transport method, server name, and certificate options are preserved. Don't disable certificate verification just to work around a connection error. Before enabling the system proxy, note your original network settings. If an app keeps connecting to an old address after a network change, client exit, or port change, check the system proxy status too. Virtual network adapter features also depend on the client implementation, system permissions, and selected core; don't assume that similarly named menu items work the same way across operating systems.

Download for macOS

Android

v2rayNG · Recommended

v2rayNG uses the Xray core; v2flyNG is an alternative client based on V2Fly. Most recent phones use arm64 packages. If you're unsure of your device architecture, check the universal package and selection notes on the download page. The apps use different core implementations, so after importing the same link, confirm that the required protocols and transport options are supported. Don't assume every setting can be copied from one app to the other unchanged.

When you connect for the first time, Android asks for permission to establish a VPN connection. This lets the app handle device traffic. Once connected, verify the result with a real request and the runtime logs. Per-app rules, battery restrictions, and background activity permissions can all affect behavior. If the connection drops when the screen turns off, first check whether Android restricts background activity. Troubleshoot subscription update failures separately from connection failures: check the URL, response format, and update path for the former; check server settings, handshake, and routing for the latter.

Download for Android

Linux

v2rayN · deb / rpm

Choose a deb or rpm package based on your distribution, then check whether your processor architecture is x64 or arm64. The download page lists common desktop packages separately from arm64 options. Package format does not determine protocol support; that depends on the core in use. If the interface won't open after installation, first read any system messages about missing dependencies or runtime requirements, then check your desktop session and permissions.

System proxy settings in a desktop environment don't automatically apply to every process. Terminal tools may read environment variables or require a SOCKS or HTTP proxy to be configured separately. The proxy protocol an app uses must match the local listening endpoint. To troubleshoot, first check the core logs for startup errors, then verify the listening address and port, and finally test a request to the destination. Before enabling TUN, understand how the virtual interface, routing table, and DNS work together. Record your existing network settings and avoid changing multiple network managers at once, so you can trace the cause of any change.

Download for Linux

View all clients →

02 / CONFIGURATION

After Downloading: Key Client Settings

Start by distinguishing inbounds from outbounds, then see how rules select a route. Subscriptions and TUN are client features, not top-level V2Ray fields with the same names.

The examples below illustrate configuration structure; they are not complete files you can use to replace all your settings. Runtime configuration generated by a client may vary with the core and interface options. Before editing, save the original and check whether you're viewing persistent settings or a temporary generated file. Changes to a temporary file may be overwritten at the next startup or server switch. To keep rules long term, manage them through the client's settings or custom configuration interface.

inbounds: Local entry point for app connections

An inbound defines the address and port that accept connections, along with the proxy protocol to use. This example listens only on the local loopback address, so apps should connect to the corresponding SOCKS port. If you change the port, update any apps with manually configured proxies. The client manages the system proxy endpoint according to its own settings. Listening on all interfaces broadens access; don't share the proxy with your LAN by default. Unlike routing rules, an inbound determines how a connection enters the core, not which server it ultimately uses.

View the JSON guide → 
{  "inbounds": [{    "tag": "socks-in",    "listen": "127.0.0.1",    "port": 10808,    "protocol": "socks"  }]}

  • Check logs before changing settings

    Read startup errors first, then connection errors. A port conflict, an unsupported field, and a failed handshake occur at different stages. If you temporarily increase log verbosity, restore an appropriate level once you've found the issue. Remove server addresses and credentials before sharing logs.

  • Change one configuration layer at a time

    Test subscription updates, core startup, the system proxy, and destination requests separately. Keep a working baseline and record each change. If something goes wrong, revert the last change; it's easier to reach a reproducible conclusion than by changing the protocol, DNS, and routing all at once.

03 / PROJECT V · V2FLY · XRAY

The V2Ray Ecosystem: Where Clients and Cores Differ

Open source describes how code and licensing are made available; protocol support, configuration compatibility, and connection results each need to be checked separately.

“V2Ray client” is often used as a catch-all for this category of graphical tools, but the interface, connection core, and server are separate components. The interface turns your selections into configuration; the core handles connections according to that configuration; and the server must use compatible settings. Understanding this chain gives you a clear place to start with downloads, configuration, and troubleshooting, rather than blaming every issue on the client.

Project V

From Project Name to Configuration Model

Project V is an open-source ecosystem built around network proxying, with V2Ray as one of its best-known core implementations. Concepts such as inbounds, outbounds, routing, and DNS are shared vocabulary across its tools. They describe how connections are handled; they aren't tied to any one provider and don't amount to a ready-to-use subscription. This guide is organized around these structures to help map options in the interface to their meaning in the configuration.

Follow the direction of a connection: an app reaches a local inbound, the core identifies its destination, routing selects an outbound, and that outbound initiates a remote connection. DNS may help resolve the destination and inform routing decisions, while logs record what happens. This sequence is more useful than memorizing every field, and explains why an open local port does not prove that the remote handshake succeeded.

V2Fly / Xray

Shared Concepts Don't Guarantee Field Compatibility

The V2Fly community carries on V2Ray development, while Xray evolved from a related codebase into an independent project with its own features and release path. The two share many configuration concepts, but supported protocols, transport options, defaults, and field requirements may differ. For features such as REALITY and XTLS, verify support in the core you're using. A file named config.json isn't necessarily interchangeable between cores.

A protocol name displayed in the client is only the starting point. Also check the transport, TLS settings, server name, and server requirements. A field supported by another core does not mean the current one will accept it. If a configuration fails to load, start with the field and section identified in the logs. If it loads but won't connect, check both sides' settings and the network path. This helps distinguish syntax errors from handshake failures.

Read about core differences →
v2rayN / v2rayNG / v2flyNG

Three Open-Source Clients, Each with Its Own Interface

v2rayN is for desktop systems, with server lists, subscription groups, system proxy controls, and configuration management. v2rayNG targets Android and uses the Xray core; v2flyNG offers an Android alternative based on V2Fly. They're all open-source clients, not different skins for the same app. Learn each client's menus, defaults, import formats, and core management on its own terms.

Graphical clients make it easier to configure connections without editing raw JSON, but they don't change the server's authentication or transport requirements. When copying a share link, keep the full contents. After importing it, check the protocol, address, port, and transport settings. Before switching clients, export any profiles you want to keep. Don't mistake an interface default for a value provided by the server. When moving between desktop and Android, also check the differences in system proxy settings and VPN-based traffic capture.

LICENSE / SOURCE

Check Licensing for Each Component

Open-source licenses set the terms for using, modifying, and redistributing code. One license name cannot cover a client, its core, and every dependency. The V2Ray core uses the MIT License; the Xray core uses the MPL 2.0 License. Graphical clients and bundled components have their own license terms. If you redistribute software or modify code, review the relevant terms and retain required notices. “Free to use” doesn't mean there are no conditions.

Public source code makes implementation details available for inspection and discussion, but it doesn't verify subscription sources, server behavior, or local settings for you. Protect subscription links and credentials, import configurations only from trusted sources, and understand the role of scripts, certificates, and network permissions. This site provides download links and configuration guidance; it does not replace component license terms or guarantee that a connection will work just because the software is open source.

UPDATE / BACKUP

Software Updates and Subscription Updates Are Different

A software update changes the client or its bundled core; a subscription update changes server profiles and groups. Software updates may alter the interface, defaults, or configuration compatibility, while subscription updates may replace addresses and connection settings. If an issue appears after an update, first identify which layer changed, then compare it with the previous version. Refreshing a subscription won't fix a local port conflict or add a feature that the core doesn't support.

Before updating, save your client settings and any custom rules you need. Afterward, test a previously working single profile first. Confirm that the core starts and a basic connection works before trying combinations of routing, DNS, and TUN. Client and core releases may follow different schedules. Decide whether to change cores based on compatibility and the features you actually need; don't replace every component without checking first.

See import and connection steps →
DIAGNOSIS / REFERENCE

Can't Connect? Find the Failing Stage

First check whether the subscription can be fetched, then whether its server details parse correctly. Next verify that the core starts and opens a local listening port, and finally test a destination request. If only some domains fail, check their resolution results and routing matches. If all requests fail, check the selected server and handshake logs first. Latency tests are not the same as requests from real apps: a test reflects one probe using a particular method and cannot replace a full connection check.

When reporting an issue, include the error text, steps taken, proxy mode, and core name. Remove subscription URLs, credentials, and identifiable server details. If a term is unclear, check the definitions of inbounds, outbounds, subscriptions, and routing, then compare them with the relevant settings. This makes the issue easier to reproduce and helps prevent mistaking “the browser isn't using the proxy” for “the protocol isn't supported.” Before combining JSON examples, check brackets, commas, array nesting, and outbound references.

See configuration and connection terminology →

04 / NOTES

Advanced Configuration and Core Guides

Explore topics from server selection to full traffic capture.

After your first connection works, explore more specific needs: server selection focuses on testing methods and service settings; core selection covers feature support; and TUN covers how app traffic enters the processing chain. The three articles below are listed newest first. Start with the layer related to your issue instead of changing the entire routing setup to fix one app's proxy settings.

View all articles →