Project V ecosystem · Configuration guides

V2Ray Help CenterClient downloads and setup

Download v2rayN View the guide

Find open-source client downloads, subscription import instructions, and JSON configuration references. Follow traffic from the system proxy through to routing rules.

Free forever Xray / V2Fly GUI clients

Client downloads

Choose your operating system first, then your processor architecture. Use v2rayN on desktop; for Android, start with v2rayNG. If you already have a V2Fly configuration, check whether v2flyNG supports it.

Windows Desktop and classic WPF editions Go to downloads → macOS Apple Silicon / Intel Go to downloads → Android Xray and V2Fly core options Go to downloads → Linux deb / rpm desktop packages Go to downloads →
Browse all clients →

Desktop installation and architecture

The Windows desktop edition of v2rayN uses a cross-platform interface, while the WPF edition retains the classic desktop experience. Menus may differ, but the basic steps—importing a subscription, choosing a server, and setting the system proxy—are the same. Choose one interface to start with; switching between two running instances can lead to conflicting port and system proxy settings. Check system requirements before installing. Before migrating, export your existing settings, then verify which core and working directory the new instance uses.

On macOS, check About This Mac for your chip details: Apple Silicon and Intel use different download options. On Linux, choose both the package format for your distribution and the right device architecture. Debian- and Ubuntu-based systems generally use deb packages; Fedora and some other distributions generally use rpm. Package format and processor architecture are separate requirements, so a matching file extension alone does not guarantee compatibility. See the platform installation guides for desktop launch options and dependency setup.

Mobile setup and post-install checks

v2rayNG for Android uses the Xray core, so its connection settings are best understood using Xray field documentation. v2flyNG is an alternative based on the V2Fly core. Most recent devices can use arm64; if you are unsure of your architecture, check the universal package details. Similar client names do not guarantee identical transport support. Before importing a configuration, check its protocol, transport, and security settings. Do not assume that an extension field supported by one core will be recognized by every client.

A successful installation only means the app can run; it does not provide a usable remote configuration. You need to supply your own subscription URL, server address, and authentication details. After importing a configuration, check that a valid entry appears in the list, then review the core logs. Avoid running multiple proxy clients at once. If the list is empty, investigate the import format or subscription response before changing routing rules. See our comparison of the three clients for details on how they differ.

V2Ray configuration reference

Trace fields along the traffic path: an app connects to an inbound, routing selects an outbound, and the outbound establishes the connection. Subscriptions and system proxy settings belong to the client management layer; they are not necessarily fields in the JSON root object.

Local listener and traffic entry

An inbound defines how the core accepts connections. If an app uses a SOCKS proxy, point it to the address and port of the corresponding inbound. Starting the core alone does not automatically route every app through it. This example listens on the loopback address, making it accessible only from the local machine, and uses a tag to identify the source for routing. If connections are refused, first check whether the port is listening and whether another process is using it, then verify the proxy type configured in the app. Client-generated ports may vary; use the actual settings rather than copying the example values.

{
  "inbounds": [{
    "tag": "socks-in",
    "listen": "127.0.0.1",
    "port": 10808,
    "protocol": "socks",
    "settings": { "udp": true }
  }]
}
Read the inbound guide

Configuration snippets vs. complete configurations

These snippets help explain what individual fields do; they are not a complete configuration that can be pasted together to connect to a remote server. A working file also needs a valid remote outbound, matching tags, and parameters supported by the current core. Merge identical root fields into one object or array; do not concatenate multiple JSON objects. Standard JSON does not allow comments or trailing commas. A neatly formatted file is not necessarily a configuration the core can parse.

With a GUI client, change common options in the relevant settings page first, then check the generated configuration. Direct edits to a config in the working directory may apply only to the current run; switching servers or saving settings may regenerate the file. For custom configurations, know which component manages the file, when it loads, and where errors are logged. The configuration reference covers the structure, inbounds, outbounds, routing, DNS, and policies in separate sections. It is most useful after you have made your first connection.

Open the JSON configuration reference

Get started with v2rayN

Start with the smallest working configuration, then add routing conditions one at a time. Change only one connection-related setting per test, and keep a copy you can restore.

STEP 01 / IMPORT

Import a subscription or configuration

Get a working subscription URL or a share link supported by the client. In v2rayN, add a source under Subscription Group Settings, save it, then update the subscription. You can import an individual share link from the clipboard. Menu locations may vary by version. After importing, check the server list to make sure it is not empty and the response was not just a web page.

In v2rayNG, use the add option to import from the clipboard or manage subscriptions. The address, port, user ID, and transport parameters in a configuration must all come from the same valid set of details; do not piece together a connection using snippets from different guides. Subscription URLs often contain access credentials, so avoid including them in public screenshots or issue reports.

STEP 02 / ROUTE

Choose a server and proxy entry point

Select the server you want to use and confirm that the core starts. On desktop, set the system proxy according to the apps you need to use, and begin with a clear, easy-to-understand routing preset. The system proxy determines how apps enter the client; the routing mode controls their outbound afterward. Check them separately—similarly named options are not interchangeable.

The first time you connect on Android, confirm the system VPN permission prompt. Granting permission lets the client create a local traffic entry point; it does not mean the remote connection has succeeded. If another VPN is already connected on the device, resolve the conflict first. Keep custom rules to a minimum during initial testing to make troubleshooting easier.

STEP 03 / VERIFY

Test requests and review logs

Make a request from an app you actually need while checking the client logs. A running core, a reachable server, and a specific app's traffic passing through the proxy are three separate things to verify. If the request is missing from the logs, check the app's entry point first. If it appears but fails, check the server parameters, DNS results, and network reachability.

Do not assume every app is working based only on a test result shown in the server list. Different requests may use different protocols and DNS paths. Once the basic connection works, enable domain routing, app rules, or automatic updates one at a time. Before closing the desktop client, check that the system proxy is cleared so apps do not keep trying to connect to a local port that is no longer listening.

Read the full guide →

Troubleshooting: what to check first

Check whether the configuration imports, then whether the core starts, whether requests reach it, and finally whether the destination connects. This order separates format, process, entry-point, and remote connection issues. For example, a port conflict is a local startup problem; updating a subscription usually will not help. For certificate errors, check the system time, server name, and relevant security settings rather than assuming the cause is routing. Keeping the exact error message is more useful than simply reporting that it does not work.

If a change causes a new problem, restore the last working settings and reproduce the issue by changing one thing at a time. Logs may contain server addresses and activity details, so remove sensitive information before sharing them. See frequently asked questions for common errors and setting limitations. If protocol, core, or transport terms are unfamiliar, start with the glossary to distinguish client interface labels from underlying protocol names.

PROJECT V / CORE / CLIENT

The Project V core ecosystem

Projects, cores, and GUI clients are different layers. Choose based on the protocols and configuration you need, then consider your operating system and preferred management approach.

Project V V2Fly / Xray GUI clients
Compare clients

Project V and V2Ray: how they relate

Project V is the project behind a set of tools and components for network communications; V2Ray is one of its best-known core names. The core accepts connections, parses protocols, matches routing rules, and establishes outbound connections. A GUI client organizes these capabilities into settings people can use. So “installing V2Ray” often means installing a client that manages the core. If you have a question about a menu or subscription, first identify the client you are using rather than searching for a button based only on the name V2Ray.

This layered architecture explains why the same technical documentation may need instructions for different interfaces. Core documentation covers which fields are valid; client documentation explains how the interface generates those fields. They address different problems. A client can choose a core, generate configuration, and start a process, but that does not make every feature consistent across different cores. This site covers first-time installation and common tasks in the usage guides, and documents raw fields and their dependencies in the configuration reference, so you can find help at the right layer.

How V2Fly and Xray relate

V2Fly is an important part of the V2Ray community's ongoing development, while Xray is a core fork developed from related code. They share some history and configuration concepts, but their protocol implementations, transport capabilities, and field requirements continue to evolve independently. When reading JSON examples, start with shared structures such as inbounds, outbounds, and routing to understand their roles, then check whether the current core supports each field. Shared root object names do not mean their options are interchangeable.

Choose a core based on the requirements of your existing configuration, not on assumptions about performance from a branch name. The protocol, security layer, and transport required by the server must all be supported by the client core. If any are missing, saving the entry in the interface does not mean it will connect. For branch-specific features, consult the relevant documentation and note which core is actually running. When compatibility issues arise, distinguish between an unrecognized field and a recognized parameter that still fails to connect; this helps avoid unnecessary changes.

What the three open-source clients do

v2rayN is a desktop client for Windows, macOS, and Linux, with tools for managing servers, subscription groups, the system proxy, and routing. Available core options depend on the client. v2rayNG is for Android and uses the Xray core; v2flyNG is also for Android and uses the V2Fly core. All three are open-source clients, but their interfaces, permission models, and configuration storage differ. Desktop screenshots are not a reliable guide to Android menus. When migrating, check the connection parameters rather than copying the entire working directory.

Open source means the implementation and licensing terms can be reviewed; it does not remove the need to check configuration compatibility. The client, core, and data files used at runtime may each have different open-source licenses. V2Fly's v2ray-core is licensed under MIT, while Xray-core is licensed under MPL-2.0. Check the relevant license texts separately for redistribution requirements covering the client and its dependencies. Focus on the source, feature set, and configuration compatibility rather than assuming every component has the same terms because it is labeled open source.

Client, core, and subscription updates

Client updates may change the interface and configuration generation; core updates may change protocol implementations and field requirements; subscription updates mainly refresh remote server information. These updates affect different things. An updated subscription does not mean the app itself was updated, and updating the client will not automatically fix an expired subscription URL. Before updating, note your current settings and export any configurations you need. Afterward, check startup logs, core selection, and routing data loading, then test with an actual app request.

The downloads page brings together platform links and installation instructions. The homepage keeps stable usage guidance rather than pinning client version details. To troubleshoot configuration issues, consider the installed client, the core currently running, and the server requirements. JSON snippets in the documentation illustrate structure; defaults, generation behavior, and supported fields in your environment still need to be checked. With these boundaries in mind, installation, migration, and troubleshooting can focus on a specific component instead of trial and error across multiple settings pages.

Configuration and deployment notes

Practical guides to desktop deployment, subscription maintenance, and DNS routing. Get a basic connection working first, then follow the guide that matches your needs.

View all articles →