Open-source clients · Setup guides

V2Ray client Setup guides

Download v2rayN View guides

Follow the steps from choosing a client to importing a subscription and verifying proxy connectivity on desktop or Android.

  • VMess
  • VLESS
  • Trojan
  • Shadowsocks

Settings at a glance

Understand where traffic enters before changing routing

System proxy settings determine how apps hand traffic to the client. Routing determines how the client forwards that traffic. Treat these as separate layers to avoid toggling settings at random when troubleshooting.

For your first setup, use the system proxy to test browser access before trying TUN mode. This separates potential issues into three areas: the client's local listener, the remote connection, and how the app connects to the client. A successful node test only confirms that the test request completed its route; it does not mean every app on your computer is using the proxy.

The five settings below cover the most common everyday tasks. The floating panels illustrate what each setting means; they do not change your device. Menu labels may vary between clients, so follow the options in your current interface. If a term is unfamiliar, check the glossary before continuing with the setup steps.

v2rayN / System proxy
System proxySet system proxy automatically
Local mixed listening port10808
PrerequisiteCore is running normally

Select a working configuration, then set the system proxy to automatic. Apps that honor the system proxy setting send requests to the local listening port, where the core handles them. This is a good way to verify your first connection, and it is easy to check what changed. Unlike TUN, the system proxy relies on apps honoring the setting. Some games, terminal apps, and software with built-in proxy options need separate configuration. After testing or before closing the client, clear the system proxy if you no longer need it, so apps do not keep trying to connect to a stopped port.

Prefer a step-by-step approach? The full setup guide starts with the basics and walks through installation, subscriptions, proxy modes, and routine maintenance.

Client downloads

Choose an installer for your operating system

For desktop, start with v2rayN; for Android, take a look at v2rayNG. Check your operating system and processor, then choose the right download option. After installing the client, import a valid configuration you are authorized to use.

Windows

Recommended: v2rayN

The download center offers Desktop and classic WPF editions. Desktop uses a newer cross-platform interface, while WPF retains the traditional desktop experience. Choose based on system requirements and personal preference; there is no need to install both just to compare their interfaces.

After the first launch, check that the core runs before importing a subscription and enabling the system proxy. If you downloaded an archive, extract all its files before running the client; do not launch it from within the archive utility. You do not need TUN to test a regular browser connection. Check permissions and system components only if you need a virtual network adapter.

Go to downloads

macOS

v2rayN

Open About This Mac to check whether your device has an Apple Silicon or Intel processor, then choose the matching installer. The same interface does not mean installers use the same architecture. Choosing the right one helps avoid startup and component compatibility issues.

After installation, follow the system prompts to grant any required permissions, then check the proxy status in network settings. If other network tools are running, quit them before testing to prevent conflicting settings. If only one app cannot connect, check whether it uses the system proxy before reinstalling the client.

Go to downloads

Android

Recommended: v2rayNG

Start with v2rayNG, which uses the Xray core. If you need compatibility with the V2Fly core, consider v2flyNG. Most modern phones use arm64; if you are unsure which architecture your device uses, check the universal version details rather than guessing from the phone brand.

After importing a configuration, start the connection and approve the system VPN permission when prompted. If the connection drops after the screen locks, check battery optimization and background activity restrictions. Android's VPN interface connects traffic differently from the desktop system proxy. When using the same subscription on both, check routing and app-specific settings separately.

Go to downloads

Linux

v2rayN

Choose deb or rpm based on your distribution's package system, then check whether your processor is x64 or arm64. These downloads are graphical clients for desktop environments, where you can manage subscriptions, switch configurations, and view connection logs.

Desktop environments handle system proxy settings differently, and terminal apps may need separate configuration. After installation, test the proxy clearly in a browser before connecting other apps one by one. Before using TUN, check your distribution's permission requirements and whether another network service already manages the same routes.

Go to downloads

Browse all clients →

First connection · 3-step overview

Import a subscription, route traffic, verify the connection

Start with the shortest working connection, then add rules. Change one setting at a time and keep the last known working setup. If something goes wrong, you will know what changed.

  1. Import a valid subscription and check its contents

    In Subscription groups, add a source name and the full URL, save, and run an update. On Android, you can do the same in subscription settings. After updating, check that the list contains entries and that the protocol, server address, and required parameters were imported. Subscription URLs and individual share links serve different purposes; do not use one in place of the other.

    If the list is empty, check whether the link has expired, contains spaces, or returns a web page instead of a subscription. Keep the original group for now rather than repeatedly deleting and recreating it; it may help you compare results. The client does not provide a remote service, so successful installation and a valid subscription are separate requirements.

  2. Choose a configuration, then enable the appropriate proxy mode

    Run a real connection test for each candidate configuration and choose one that completes a request. On desktop, enable automatic system proxy configuration. On Android, start the connection and approve the system permission. Latency readings are only a rough comparison under the same conditions; a single low reading does not guarantee reliability or download speed.

    For your first setup, stick with the default or a commonly used routing profile. Do not run multiple proxy clients at once or start by combining TUN, custom DNS, and complex routing rules. If the core will not start, address the specific error in the logs first; changing browser settings will not fix a port that is not listening.

  3. Verify that app traffic is actually using the proxy

    Open the page you want to test and check the client's connection logs or traffic counters. If needed, compare access with the proxy enabled and disabled to confirm that the request takes the expected route. Browser access only confirms that this browser request succeeded; it says nothing about the network paths used by terminal apps, games, or background processes.

    If some sites fail, narrow down the cause in this order: app settings, DNS, routing rules, then the remote configuration. After each change, repeat the same test rather than switching to a different target. Once the connection works, note the working configuration, proxy mode, and local port. This gives you a clear baseline after client updates or network changes.

Read the full setup guide → Find help by symptom →

Project V · V2Fly · Xray

Clients, cores, and the open-source ecosystem

Start by distinguishing three layers: V2Ray is part of the Project V proxy ecosystem; V2Fly and Xray are related core projects; and v2rayN, v2rayNG, and v2flyNG are graphical clients for end users. Choosing a client determines how you manage the software; choosing a core determines how it processes configurations.

Project V: from core capabilities to graphical interfaces

Project V provides modular tools for proxy communications, with the V2Ray core handling inbound and outbound traffic, transports, and routing. Graphical clients organize these capabilities into menus, groups, and settings pages, so users do not have to start by writing an entire configuration by hand. Saving a setting in the interface often changes a parameter read by the core.

A client opening successfully does not mean its core has started correctly, and a core starting successfully does not guarantee that the remote configuration is valid. This guide checks the interface, core, and network as separate layers. Once you understand how they relate, you can tell whether an error calls for checking settings, startup logs, or connection logs.

V2Fly and Xray: choose based on feature compatibility

V2Fly continues the development of the V2Ray community ecosystem, while Xray has evolved separately from related code. The two share technical roots but have their own features and configuration changes. Using the same protocol name does not guarantee identical transport options, extension fields, or default behavior. Check support in both the client and the core you plan to use.

For features such as REALITY, confirm that both the core and client recognize the required parameters. Successfully importing a share link alone does not prove compatibility. Before switching cores, record your routing and DNS settings. If the configuration will not start, look for a specific field error first rather than assuming every connection failure is caused by the remote service.

Three open-source clients, each for a different use case

v2rayN is for desktop platforms and helps manage configurations, subscriptions, and proxy modes in one place. v2rayNG is for Android and primarily uses the Xray core. v2flyNG offers an Android option based on the V2Fly core. All three are open-source projects, but they are not simply the same interface under different names. Check their menus, supported parameters, and release schedules separately.

Open-source licenses define how code can be used, modified, and distributed; a client and its integrated core may also use different licenses. Open source enables review and collaboration, but does not make every runtime environment, subscription source, or configuration trustworthy. Consider the project's maintenance status, permission requirements, and whether the configuration matches your chosen client.

Updates: keep your configuration and verify changes one at a time

Community maintenance can fix bugs, update dependencies, and add features, but a new interface or core may move options or change how parameters work. Before updating, save any local configuration you need and review release notes for platform, runtime, and compatibility details. Avoid changing the client, core, subscription, and rules all at once while troubleshooting.

After updating, retest core startup, subscription import, regular proxy connections, and commonly used routes. Check TUN mode if needed. Updating a subscription only fetches remote configuration; it does not update the client software. This site organizes download links and setup guides, but cannot control third-party subscription content or remote service availability. Follow the laws where you live and the policies of the network you use.

Learn more about the ecosystem and this site's scope: About this site; for a step-by-step guide to configuration, read the full setup guide.

Recent technical guides

Installation, subscriptions, and port troubleshooting

Choose an article based on what you are seeing. At installation, check the runtime environment first; for subscriptions, verify the contents; if the core will not start, check the port. Keep the original error message—it's more useful than repeatedly changing configurations.

Browse all articles →