CLIENTS / CONFIGURATION

V2Ray Downloads Setup Guides

Download v2rayN View Guides

Choose an open-source client such as v2rayN for your platform, then work through subscription setup and routing one setting at a time.

  • JSON Configuration Fields
  • Xray · V2Fly
  • GUI Client Guides

This settings window is a static illustration. Check the actual client for port values and menu names.

01 / DOWNLOAD

Choose a package for your platform

Use v2rayN on desktop. On Android, start with v2rayNG and consider v2flyNG if you need its core.

Windows

v2rayN comes in a desktop edition and a classic WPF edition. The desktop edition uses a newer cross-platform interface, while the WPF edition retains its familiar layout. Choose the interface you prefer, then check the download page for system requirements. You don’t need to install both just to import the same subscription.

After the first launch, make sure the app can write to its configuration directory before adding a subscription group. When migrating from an older setup, save your existing configuration and custom routing rules; don’t copy the old directory over the new installation. If startup fails, first determine whether the issue is with the runtime environment or the configuration.

Go to downloads Windows package

macOS

v2rayN provides separate download options for Apple Silicon and Intel processors. Check About This Mac for your chip: choose arm64 for Apple Silicon or x64 for Intel. This choice is unrelated to subscription protocols and should not be based on the server’s processor.

After installation, launch the client and select a server before configuring the system proxy. If your browser has a proxy extension, check whether it overrides system settings. Terminal apps may use separate environment variables, so access from a browser doesn’t mean every app follows the same connection path.

Go to downloads macOS package

Android

v2rayNG uses the Xray core, while v2flyNG uses the V2Fly core. On most recent Android devices, start by checking the arm64 package; if you’re unsure of the architecture, look for a universal build. Choose between the apps based on configuration compatibility and core requirements, not similar-looking filenames.

The first connection requires permission to establish a VPN connection, allowing the client to route app traffic. If the connection drops when the screen locks, check battery optimization and background restrictions. Per-app proxy settings determine which apps use the proxy; confirm whether the rule means bypass or proxy-only before applying it.

Go to downloads Android package

Linux

v2rayN offers deb and rpm packages. Choose the format used by your distribution’s package manager, then select the processor architecture: x64 or arm64. Package format determines how the app is installed; architecture determines which processors can run it. Check both.

Once installed, launch the GUI client in your desktop session and check that the local listener is working. System proxy support varies across desktop environments, and some apps require you to enter the proxy address and port manually. A successful installation doesn’t mean every app is using the proxy.

Go to downloads Linux package

The package contains only the client application. Subscription URLs, server connection settings, and access permissions come from your configuration provider; you’ll still need to import a valid configuration after installation. The download page covers architectures and package formats, while the client comparison explains which environments suit each app.

View all clients →
02 / CONFIG OBJECTS

Configuration Object Index

Find the relevant client setting, then see which layer of the configuration it affects.

Subscription Groups: Organize Sources and Updates

Subscription groups are managed by the client; they are not a standard top-level field in core JSON. Add a distinct label for each source, enter its subscription URL, and update it. Then check that server entries were created. If an update fails, distinguish an unreachable URL from unparseable content or a problem with the current network path before taking action. Groups are easier to maintain than individual entries when sources update regularly, but whether local edits persist depends on the client. Save important settings separately.

Subscription Group
├─ Label
├─ Subscription URL
└─ Update Subscription

Client interface settings don’t map one-to-one to core configuration. The client stores subscription groups and window preferences; inbound, outbound, routing, and DNS are common core configuration objects. Before editing anything manually, check whether you’re changing the client’s settings or its generated runtime configuration. The latter may be regenerated at the next startup.

Explore JSON structure and configuration fields →
03 / QUICK START

Three Steps to Configure v2rayN

Follow this order: configuration source → traffic entry point → connection result.

  1. Step 01

    Import a Subscription and Select a Server

    Open subscription group settings, add a recognizable label for the source, and paste the full subscription URL. Save and update the group, then confirm that usable configurations appear in the list and select a server. For a single share link, use the client’s import option rather than entering it as a subscription URL.

    A successful import means the content could be parsed; it doesn’t guarantee that the server is reachable. Check that the address, port, protocol, transport, and security settings all come from the same configuration. Subscription URLs may contain access credentials, so don’t include them in public screenshots or support requests. Remove sensitive fields before sharing logs, too.

  2. Step 02

    Check the Proxy Entry Point and Routing Mode

    After connecting, make sure the client hasn’t reported that its listening port is already in use, then enable the system proxy if needed. Browsers can usually read system settings, but terminal and some desktop apps need separate configuration. If you enter the proxy manually, make sure the address, port, and protocol match the client’s actual listener.

    Next, choose a routing mode that fits your needs. Routing determines where requests go after entering the core; the system proxy determines whether apps send requests to the core in the first place. They are separate settings. If you’re new to this, keep the client’s default rules initially. Once the connection works, add your own domain or address conditions one at a time.

  3. Step 03

    Test Apps and Check Logs

    Use the app that needs the proxy to access a destination, then check whether the client records the connection. If only one app fails, check its proxy settings. If every app fails, check the core status, server settings, and network connectivity. Change one setting at a time so you can identify what made the difference.

    Connection refused, timeout, and handshake failure indicate different stages; they don’t all mean the subscription is invalid. Temporarily increasing the log level can help pinpoint the issue, but restore the usual level once it’s fixed. On Android, also check VPN permission and per-app scope. If the connection drops in the background, check battery optimization instead of repeatedly importing the subscription.

Before moving to a new device or client, save the source of your working configuration and any custom rules. Don’t enable the system proxy, complex routing, and LAN sharing all at once. Start with a minimal working setup, then add features one at a time. This makes settings easier to troubleshoot and gives you a clear baseline.

View the full guide →
04 / OPEN SOURCE ECOSYSTEM

Project V, Cores, and Clients

Separate the ecosystem, runtime core, and GUI to see which layer a configuration applies to.

Ecosystem Overview

How Project V Relates to V2Ray

Project V is an open-source ecosystem of network proxy tools and related capabilities, with V2Ray as one of its widely used core projects. In everyday searches, “V2Ray client” often means a GUI manager; technical documentation may use V2Ray to refer specifically to the runtime core. These are different layers, so identify the context when reading a guide.

Cores typically use configuration files to define inbounds, outbounds, and matching rules. GUI clients turn those objects into forms, lists, and menus. So a setting you can find in the interface doesn’t mean every core accepts the same JSON. Understanding this distinction is more useful for maintaining configurations than memorizing where a menu item is.

Core Families

V2Fly and Xray: Compatibility Boundaries

V2Fly continues the community development of V2Ray, while Xray emerged from the wider ecosystem and has developed its own capabilities. The two share some concepts, but differ in protocol implementations, transport options, and configuration details. For features such as REALITY and XTLS Vision, check Xray’s support rather than relying on whether the client name includes V2Ray.

Support for a protocol doesn’t necessarily mean support for every combination that uses it. Transport, security layer, flow control, and core features all affect compatibility. If an error appears after switching cores, check the parsing message first, then investigate the runtime connection. Don’t mistake an incompatible configuration for an unreachable server.

Open Source and Licensing

What the Three GUI Clients Do

v2rayN, v2rayNG, and v2flyNG are open-source GUI clients for managing configurations on desktop and Android. v2rayN provides a cross-platform desktop interface, v2rayNG works with Xray, and v2flyNG works with V2Fly. Choose based on your operating system and configuration requirements; there’s no need to install multiple clients just because their names are similar.

Open source means the code is available under the relevant licenses. Copying, modifying, and redistributing it are still subject to the terms of each project and its dependencies. A client and its core may have different licenses, so one general label can’t replace the license details for each. The client app may be free to use, while server resources and subscription services are separate offerings.

Updates and Maintenance

Clients, Cores, and Rules Update Separately

A client update may change the interface, configuration generation, or bundled core. A subscription update primarily refreshes server configurations; a rules update changes domain and address lists. These updates serve different purposes: an updated subscription doesn’t mean the app or core is up to date. Record your actual environment before troubleshooting so you can find the right field reference.

Before updating, save custom routing, DNS settings, and subscription group details. Afterward, test existing connections and check whether custom rules still work. If parameter names or defaults have changed, refer to the current interface and documentation for the relevant core. This page helps you explore configuration objects; the download page covers installation choices, and the configuration reference explains each section of the JSON.

Choose a reading path based on what you need: compare clients to choose an app, follow the guide to make your first connection, or consult the configuration reference for a specific field. If a subscription update fails or the system proxy doesn’t work, identify the stage where the problem occurs before opening the relevant troubleshooting guide. This keeps issues at different layers from getting mixed together.

About this site and its scope →FAQs and connection troubleshooting →
05 / READING

Configuration and Troubleshooting Guides

Understand the reasoning behind settings, from core differences and protocol choices to Android behavior.

View all articles →