Client installation / Config files / Routing rules

V2Ray Setup Guide

Start with subscription imports, then learn about config files and traffic routing.

  • JSON
  • Xray · V2Fly
  • Open source

CLIENT SETTINGS / CLIENT CONFIGURATION

V2Ray setup guides, starting with client settings

First, understand the difference between the client interface and the proxy core. The client stores server details, updates subscriptions and generates runtime configuration; the core accepts connections, matches routing rules and forwards traffic. The five guides below follow a practical setup sequence. The interface mockups illustrate menus and configuration relationships—they do not show the current state of your device.

v2rayN / Subscription group settings · Interface example
  • Servers
  • Subscription groups
  • Settings
  • Routing settings
Group nameEveryday use
Subscription URLPaste the full URL
Update subscriptionTry direct connection first

Once the update finishes, select an active configuration from the server list.

Subscription URLs and share links

A subscription URL retrieves and updates multiple server configurations; a share link usually describes a single configuration. In v2rayN, save the URL in subscription group settings, then update it. In v2rayNG, add it from the subscription group menu. Before importing, make sure you copied the complete URL—not a page title or sign-in page address. For the first update, try a direct connection; use a proxy only if the subscription provider explicitly requires one. URLs may contain access credentials, so keep them out of public screenshots. After importing, select an active configuration: seeing an entry in the list does not mean a connection has been established.

View the configuration reference →

Your first setup: establish the simplest connection path

Get a working server configuration or subscription URL. Import it, select a configuration and enable an appropriate proxy entry point. Use a browser to visit a known reachable destination and check whether the corresponding connection appears in the client logs. This only verifies the current configuration with the current app; there is no need to enable complex routing, a virtual interface or custom DNS yet. Once the basic path works, add settings one at a time and keep a way to restore the previous working state after each change.

Interpret test results separately. A server entry means the client accepted its format. A port test may show that one layer is reachable. Opening a webpage additionally involves DNS resolution, the transport handshake and the app's request. These tests measure different things. When results disagree, record how each test was run and check the logs; that is more useful than comparing a single latency number.

Read the configuration by following the traffic flow

To understand JSON configuration, read the inbound, routing and outbound sections in order. Inbounds describe where local connections enter; routing determines how they are handled; outbounds specify where traffic goes next. DNS handles relevant lookups, while policy settings adjust connection management. Ports and rules in tutorials are syntax examples only. Use the client settings for your actual setup, and do not assume every client uses the same default port.

Graphical clients may regenerate configuration files at startup, so direct edits to generated files might not persist. Prefer the client interface for custom routing or configuration, and export a backup before making changes. For field types, array structures and tag mappings, see the V2Ray configuration reference. If terms such as inbounds, outbounds and transports are unfamiliar, start with the glossary.

DOWNLOAD / PLATFORMS & INSTALLERS

Download v2rayN: choose your device

Use v2rayN on desktop. For Android, start with v2rayNG, or consider v2flyNG if you need V2Fly compatibility. Check your operating system, processor architecture and installer format before choosing a file on the download page. A client and a subscription are separate: installing the client does not provide server settings, and importing a subscription does not replace installation or permission steps required by your system.

Windows

v2rayN / Desktop · WPF

The download page offers the desktop edition and the classic WPF edition. The desktop edition uses a cross-platform interface, while WPF retains the classic desktop experience. Choose based on your system and preferences; you do not need to run both clients with the same configuration. Close existing instances before installation to avoid occupying local listening ports.

After the first launch, import a configuration and confirm the local service is running before setting up the system proxy. If your browser still uses its own proxy extension or manual settings, check its connection entry point separately. If you change the listening port, update any apps that depend on it.

Go to downloads Windows client

macOS

v2rayN / Apple Silicon · Intel

Check your chip type in About This Mac, then choose the Apple Silicon or Intel installer. Architecture is unrelated to the server protocol, so do not infer it from the subscription name. Follow the installation prompts to place the app, and review any system permission and security notices on first launch.

System proxy and TUN mode require different permissions; start by verifying the connection with a regular proxy. If only one app cannot connect, check whether it honors the system proxy before routing all device traffic. The download page lists architecture options and what to check before installing.

Go to downloads macOS client

Android

v2rayNG / v2flyNG

v2rayNG uses the Xray core, while v2flyNG uses V2Fly and may suit configurations that require it. For most newer devices, check the arm64 package first; if you are unsure of the architecture, look into the universal package. Installation also depends on system and app requirements, so a device's purchase year alone is not a reliable guide.

After importing, select a configuration and start the connection. On first launch, you may need to approve the system's network connection request. Battery-saving restrictions can interrupt background operation; if the connection drops when the screen locks, check the app's background permissions. Subscription URLs and QR codes may contain access credentials, so hide them before sharing screenshots.

Go to downloads Android client

Linux

v2rayN / deb · rpm

Choose deb or rpm to match your distribution's package system, then check whether the device uses x64 or arm64. Package format and processor architecture are separate requirements; a downloadable file is not necessarily installable on your system. The desktop environment and required runtime dependencies must also meet the client's requirements.

Desktop environments vary in how they support the system proxy, and terminal apps may not use desktop proxy settings at all. When testing, distinguish browser connections from command-line connections and check each one's proxy entry point. First verify that the graphical client and local listener work, then look into virtual interface permissions and system routing.

Go to downloads Linux client

If a client is already installed, save your subscription groups, custom rules and any essential app settings before updating. Do not overwrite your only working setup until you have confirmed configuration compatibility. An installer addresses software deployment; troubleshoot connection issues separately by checking configuration, proxy entry points, routing and logs in sequence.

Browse all clients →

PROJECT V / CORES & GRAPHICAL CLIENTS

The V2Ray open-source ecosystem: projects and clients explained

V2Ray is both a common search term and a name associated with software and configuration systems in the Project V ecosystem. Most day-to-day setup happens in a graphical client, while the selected core handles traffic forwarding. Understanding this distinction helps you determine whether a guide, JSON configuration or installed client applies to your setup.

Ecosystem overview

Project V

Core projects

V2Fly / Xray

Graphical clients

v2rayN / v2rayNG / v2flyNG

Project V and configuration structure

Project V is built around modular proxy capabilities. V2Ray configuration covers inbounds, outbounds, routing, DNS and connection policies. Modularity lets the same local entry point work with different outbounds, but it also means a protocol name alone cannot describe a complete connection. When reading a configuration, check authentication details, transport and security together rather than matching just one name.

The V2Fly community continues development and maintenance of V2Ray-related implementations, while Xray has evolved into an independent core project based on related technology. They share some concepts and configuration conventions, but their features, fields and release schedules are not identical. A configuration that works with one core still needs to be checked for compatibility with another, especially when it uses specific transport or security features.

Graphical clients and open-source software

v2rayN, v2rayNG and v2flyNG are all open-source graphical client projects. Open source makes their implementation, change history and license terms available for public discussion, but it does not mean every third-party configuration is safe to import. Clients make it easier to manage configurations, run a core and view logs. Server parameters and subscription sources still need to be assessed on their own merits.

On desktop, v2rayN makes it easy to manage subscriptions, system proxy settings and routing in one place. v2rayNG and v2flyNG organize their interfaces around Android connection permissions and background operation. They are separate programs, not different names for the same app, so their menus and settings do not have to match. Choose based on your device and configuration needs, then follow the guide for that client rather than applying desktop instructions to a mobile interface.

Open-source licenses and component boundaries

Open-source licenses set the terms for using, modifying and distributing code; they are not the terms of service for a subscription provider. Cores, graphical clients and bundled dependencies may use different licenses, so refer to each project's documentation. The MIT license used by V2Ray-related core implementations and the MPL 2.0 used by Xray-core describe the licensing terms for their respective code; they do not imply that every component uses the same license.

A site's name does not define its project identity. This site is a Chinese-language guide to clients and configuration, explaining the technical relationships between Project V, V2Fly and Xray without conflating a tutorial site with a core project. To determine whether a feature is available, check the installed client's interface, bundled documentation and runtime logs—not just a product abbreviation in search results.

Updates and troubleshooting

Client updates, core updates, subscription updates and routing resource updates solve different problems. A client update may change the interface or how configuration is generated. A subscription update fetches server entries, while a routing resource update affects domain or address matching. Updating a subscription usually does not replace the client, and installing a new client does not automatically fix server settings in a subscription.

When something goes wrong, note recent changes first, then check the logs. For configuration parsing errors, check fields, syntax and core compatibility. For a local port conflict, look for duplicate client instances. For a failed handshake, verify the time, destination address and security parameters. Remove subscription URLs, user identifiers and authentication details before sharing logs publicly. Troubleshooting layer by layer preserves more useful clues than reinstalling, switching cores and rewriting routing rules all at once.

READING NOTES / CONFIGURATION GUIDES

V2Ray technical guides: find answers by topic

Once your basic connection works, explore the topics related to your specific questions. If an import fails, start with the format guide; for configuration choices, compare protocols; for connection issues, begin with the runtime logs. Each guide focuses on a particular problem and can be read alongside the field descriptions in the configuration reference.

Download client