Open-source clients for Android and desktop

V2Ray Android Downloads

Choose v2rayN for desktop and v2rayNG for Android. Start by picking the right installer, then import a subscription and configure routing.

  • VMess
  • VLESS
  • Trojan
  • Shadowsocks

Connection problems and settings to check

First identify where the problem occurs. Updating a subscription retrieves configuration; enabling the system proxy changes how some apps connect; routing rules determine where traffic entering the client goes. These steps are not interchangeable. When troubleshooting, change one setting at a time and retry with the same app to see which change made a difference.

Common issues

  • System proxy is on, but the browser still connects directly. Check the browser's own proxy settings first. Then determine whether requests are reaching the client or matching a direct-routing rule.
  • The list is empty after updating a subscription. Saving a URL only creates a group entry. The update may have failed, or it may have populated a different group.
  • On Android, the connection drops soon after the screen locks. If it comes back when you reopen the app, check the system's background restrictions before changing your connection configuration.

Settings to check

  • In v2rayN, select “Set system proxy automatically.” Make sure the browser uses the system settings, then check Routing Settings to see whether the destination matches a direct rule.
  • Open “Subscription groups,” select the group you just saved, and update its subscription. If parsing fails, make sure the URL is a subscription link, not an account sign-in page.
  • Check the battery settings for v2rayNG in Android's app info. If “Unrestricted” is available, try it temporarily and compare the connection after locking the screen. Keep it only if it helps.

Routing rule example: when a destination matches the private IP list, send it through the outbound tagged direct. This tag must match the name of an existing outbound.

{
  "type": "field",
  "ip": ["geoip:private"],
  "outboundTag": "direct"
}

Five client settings

Subscription groups and refreshing the list

Subscription groups are useful for managing connection configurations that change over time; a single link is better when you only need to import one configuration. In desktop v2rayN, save the URL under “Subscription groups,” then update the current group. In Android v2rayNG, open subscription group settings from the side menu, save the URL, and return to the main list to update. Make sure the new entries appear in the right group, then select a configuration to connect. If refreshing overwrites custom entries, save them in a separate group instead of editing subscription entries repeatedly.

Subscription groupUpdate current subscription

This interface preview brings settings together for comparison; it does not represent the actual menu order. If your client uses different labels, start with Concepts at a glance. Identify whether you need to change the traffic entry point, destination matching, or the connection configuration itself, then open the relevant menu.

Choose a download for your operating system

First decide which device you are installing on, then check its operating system and processor architecture. Packages for the same architecture are not interchangeable across operating systems. If the app is already installed, check which client and release type you have before updating.

Start with desktop v2rayN, or choose WPF if your guide uses the classic interface. Check Settings → About → System type before downloading.

If the app closes before opening a window, check the release notes for runtime requirements.

Download

Check “Chip” or “Processor” in “About This Mac,” then choose the Apple Silicon or Intel package accordingly.

Move the app to Applications as directed and launch it there, not from the disk image.

Download

Choose v2rayNG unless you need V2Fly. Most newer devices support arm64. If unsure, check the requirements for the universal package.

If an update fails, back up subscriptions and manually added entries before uninstalling.

Download

Choose deb for Debian or Ubuntu, or rpm for Fedora. Check that the package matches your CPU architecture.

Check the desktop proxy settings and test with an app that uses them. Some apps need separate configuration.

Download

Browse all clients →

Three steps: import, connect, verify

For your first connection, keep the default settings and establish a baseline with a configuration you know works. Once connected, adjust routing, per-app selections, or background settings. If something goes wrong, you can return to the previous step and test again.

  1. Import a configuration and select it

    If you have a subscription URL, create a group in the client, enter a name you can recognize and the URL, save it, then update the group. If you only have one share link, use the import-from-clipboard option; there's no need to create a subscription first. After importing, check that the expected entry appears in the main list and select one to test. If the client reports that no configuration was found, make sure you copied the full URL or share link—not the text next to a QR code. Subscription URLs may contain access credentials, so don't include the full URL in public screenshots or support requests.

  2. Connect a test app

    On desktop, select a configuration in v2rayN, choose “Set system proxy automatically,” then open a browser that uses the system proxy. On Android, tap Connect in v2rayNG. When Android first asks to authorize the system VPN, check which app initiated the request before granting access. Don't change the per-app list during the test, and check that no other VPN is using the system connection. If an error occurs before enabling the proxy or granting system access, troubleshoot app startup, runtime requirements, or permissions first—not routing rules.

  3. Use a real request to pinpoint the problem

    Open a page you visit regularly, make a new request, and note the time. Then check the client's runtime log for an entry at that time. If there's no matching entry, check whether the test app is using the client. If the log shows a direct connection that should have used a proxy, inspect the matching rule. If a connection attempt times out, check your local network, connection configuration, and server status in that order. When testing is complete, restore the original system proxy setting or disconnect the Android VPN, then retry in the same app to confirm the connection changes as expected.

Read the full guide →

Project V, its ecosystem, and client licenses

Projects, cores, and clients are three distinct layers. Identify which one the documentation refers to before deciding whether a feature belongs to a connection protocol, a core implementation, or a client setting.

Project V and community development

Project V is the project ecosystem that V2Ray originally belonged to. The V2Ray core handles inbound connections, outbounds, and routing. The V2Fly community continues to maintain the V2Ray core, while Xray branched from the same code lineage and has evolved independently. In everyday use, “V2Ray” can mean the core or serve as a general term for this category of tools. When a guide says “V2Ray compatible,” check whether it means the client can import a particular share-link format or actually connect using the required protocol and transport settings.

Xray and V2Fly compatibility

The two core families share some configuration concepts, but using the same protocol name does not mean all transport and security settings are compatible. Check the protocol separately from any additional fields: a VLESS configuration, for example, may also require specific transport or security options. If a client can display an imported configuration but fails to start or complete a handshake after a core switch, compare each field against the supported options and confirm what the server expects. An imported configuration is not necessarily a compatible one.

Three open-source GUI clients

v2rayN is for desktop and manages subscriptions, settings, and the system proxy. v2rayNG uses an Xray-based core to route Android app traffic through the system VPN service. v2flyNG uses a V2Fly core and offers another option for Android users with compatible configurations. All three GUI clients are released under the GPL-3.0 open-source license and are free to use. The client license does not determine the licenses for the core or other components, and does not include a working server or subscription service. Choose a client based on the settings in your configuration.

What to check before and after an update

Clients, cores, and routing rule data may be updated separately. A client update can affect the interface or system integration; a core update may change how configurations are parsed and connections behave. If only a few domains use the wrong outbound, check the active routing rules and data before changing both the client and core. Before updating, note the active group, routing preset, and app scope. After updating, test a connection that worked before, then try the new configuration to distinguish migration issues from existing problems.

Compare the three clients and see which one fits →

Runtime logs and troubleshooting

A window that won't open, a single connection that times out, and a handshake error in the logs each call for a different starting point. Choose the guide that best matches what you're seeing. If multiple apps are affected, work through the symptoms in Troubleshooting.

Browse all articles →