Client downloads and setup guides

V2Ray Official Site · v2rayN
Client downloads and cross-platform setup

Download v2rayN View guides →

From choosing a client to importing a subscription, follow the steps to configure routing and proxy settings.

  • VMess
  • VLESS
  • Trojan
  • REALITY

Import subscriptions and manage groups

A subscription keeps a set of connection configurations available through a single update source. In v2rayN, add the address under Subscription Groups and update that group; in v2rayNG, use the subscription group settings for the same task. Groups are easier to organize by source than individual entries, and can be updated or troubleshot separately. After the first import, check that configurations appear in the list, then select one to use. Updating a subscription refreshes configurations—it does not enable the system proxy. Subscription URLs may contain access credentials, so redact the full link before sharing screenshots. Before converting a subscription, make sure you trust the service receiving it.

View guide →
Subscription groupsSubscription group settings
RemarksPersonal subscription
AddressEnter the full URL provided by your subscription provider
Update subscriptionUpdate group

Choose a client for your platform

Check your operating system and processor architecture before choosing an installer. The download page lists options and requirements for each platform.

Browse all clients →

Windows

Top pick for Windows

Desktop and classic WPF editions

On a Windows PC, you can use v2rayN. The desktop edition has a cross-platform interface, while the WPF edition retains the classic desktop interface. Menus and settings may differ, so check which interface you have before following a guide. Most everyday tasks start with subscription management, selecting an active configuration, and enabling the system proxy. There is no need to adjust every setting at once.

Before downloading, check your device architecture and system details in Settings, then review the download page's requirements. After installation, leave the default listener settings in place, import an existing configuration, and test browser access. If TUN prompts for permission, follow the installation instructions. If the system proxy works but one app still cannot connect, first check whether that app uses the system proxy rather than assuming the subscription has failed.

Go to downloads →

macOS

v2rayN

Downloads for Apple Silicon and Intel

Mac users can use v2rayN to manage subscriptions and routing. Before downloading, open About This Mac and check whether your device has an Apple chip or an Intel processor, then choose the matching installer. Choose based on your hardware, not the computer's appearance or purchase year. The right build can help avoid compatibility issues.

After installation, launch the client from Applications and follow any permission prompts. If macOS displays a security warning, verify the file source and app details; don't disable system security protections altogether. For your first connection, start with the system proxy and consider TUN only after confirming the configuration works. If your browser loses internet access after you quit the app, check whether the network proxy settings still point to a local listener that is no longer running.

Go to downloads →

Android

Top pick for Android

v2rayNG · Xray / v2flyNG · V2Fly

For Android, start with v2rayNG. If your configuration requires the V2Fly core, consider v2flyNG. Most recent mainstream phones use arm64. If you're unsure which architecture your device supports, read the download page first to see whether a universal installer is needed. The installer architecture determines whether the app can run; the core family affects protocol and parameter compatibility.

The first time you connect, Android may ask for permission to establish a VPN connection. Check which app made the request before approving it. Allow the client to run in the background as needed, so battery-saving settings don't stop it when the screen is locked. If another service is using the system VPN connection, resolve the conflict first. A successful import doesn't mean traffic is being routed yet—check the client status, system prompt, and how apps actually connect.

Go to downloads →

Linux

v2rayN

deb or rpm packages, matched to your distribution and architecture

On a Linux desktop, you can use the v2rayN graphical client. Choose an installer based on both your distribution's package format and your device architecture: don't choose deb or rpm based only on file size, and don't mix up x64 and arm64. Check your distribution and processor details in system information, then find the matching download on the downloads page.

After installation, launch the app from your desktop menu and make sure the window opens before importing a subscription. System proxy support varies across desktop environments, and some apps need a proxy configured in their own settings. TUN involves a virtual network adapter, permissions, and routing, so follow the platform guide step by step the first time. If other network services are running on your computer, make sure the listening port is available and keep your original network settings so you can restore them if something goes wrong.

Go to downloads →

Three steps to your first connection

Get a basic connection working first, then fine-tune DNS, routing, and which apps are covered.

Read the full guide →

  1. Import a subscription and verify its source

    Get the full subscription URL. In the client's subscription group settings, add a group, enter a recognizable name, save it, and update the group. If you have a single share link, use the appropriate import option instead of entering it as a subscription URL. After the update, check that configurations appear in the list. If the list is empty, the format is invalid, or the request fails, verify that the URL is complete and hasn't expired, and that your current network can reach the subscription service.

    A subscription URL may allow others to access your connection configurations, so treat it as sensitive information. When troubleshooting, share only the error text needed; never expose the full URL, identity fields, or connection credentials. Before converting a subscription, check whether the client can already read it directly, and avoid sending it to an additional service unnecessarily. See the subscription import guide for details.

  2. Select a configuration and choose how traffic is routed

    Select an active configuration from the list, then choose the appropriate system proxy or connection mode. On desktop, start with automatic system proxy configuration so browsers that follow system settings can send requests through the client. On Android, start the connection as prompted by the client and approve the system request. Use an existing routing preset for now, and hold off on changing listener addresses, DNS, or complex rules to avoid changing too many variables at once.

    System proxy and routing handle different parts of the connection: the system proxy determines how an app passes requests to the client, while routing determines which outbound handles those requests. Even with global routing selected, apps that ignore the system proxy may not be covered. If you need to route traffic from more apps, follow the system proxy and TUN guide to enable settings one at a time, and check for conflicts with other network tools.

  3. Test access, then adjust routing

    Open the site you want to reach, plus one site expected to connect directly and one LAN resource. Confirm that proxy access, direct access, and the local network all work as expected. A successful client launch only means the service is running; test results in the list don't replace checking access from a real app. If needed, look for errors related to the request in the logs and distinguish DNS failures, connection timeouts, authentication errors, and routing mismatches.

    Once the basic connection works, change routing or DNS one setting at a time and test again after each change. To undo a change, restore the previous settings instead of resetting everything at once. Stop the connection normally when you're finished and make sure system network settings are restored. If only one app has a problem, check its own proxy settings first. For selective routing, see the routing rules introduction; for platform permissions, consult the complete setup guides for all platforms.

The Project V ecosystem and core differences

Understanding the roles of the client and core can prevent confusion when choosing or switching tools. The graphical interface stores subscriptions, selects configurations, organizes settings, and displays logs. The core reads the generated configuration and handles protocols, transport, routing, and connections. Whether a setting in the interface takes effect depends both on how the client generates parameters and whether the core supports them. Don't assume every feature is identical just because apps have similar names or display the same protocol label.

How Project V, V2Fly, and Xray relate

Project V is an open-source proxy tool ecosystem built around V2Ray. V2Fly continues and develops related core implementations, while Xray is another core branch that emerged from this technical background. They share some concepts and configuration conventions, but their features, parameter support, and behavior are not identical. When comparing V2Ray cores, specify which implementations you're comparing rather than treating all related graphical clients as the same program.

VMess, VLESS, and Trojan are connection protocol names; REALITY is a security-layer technology. They belong to different layers and aren't interchangeable options. A complete connection may also require transport settings, a domain, port, and identity fields. If a client recognizes a share link, that only means it could parse the format. Whether it can connect depends on compatibility between the core, server configuration, and current network conditions. Get the correct parameters before changing protocols.

What three open-source clients do

v2rayN is designed for desktop use, with tools for managing subscriptions, switching configurations, and adjusting routing. 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; check each app's installer and interface documentation for specific features. Choose based on your device first, then your configuration requirements. There's no need to keep switching between apps just because their names are similar.

Desktop and mobile operating systems handle traffic differently. The same subscription may behave differently after import because of system permissions, background policies, or DNS behavior. For example, desktop apps may follow the system proxy, while Android typically requires the client to start a system VPN connection. You can reuse a subscription you legitimately have access to, but don't assume another device will automatically inherit routing modes, permissions, or background settings.

Open-source licenses and component boundaries

Open-source code can be read, used, and redistributed under the terms of its license. That doesn't mean every component uses the same license. Graphical clients, cores, and bundled components may each have their own license notices. If you plan to modify, repackage, or redistribute software, review the applicable terms for each component and retain any required copyright and license information. Open-source status also doesn't replace the need to assess subscription sources, configuration content, or system permissions.

Client downloads and remote services are separate concerns. A client provides local management and connection tools; remote service availability, permissions, and access conditions depend on that service. If installation succeeds but no configuration is available, or an existing subscription can't be updated, the cause can't be inferred from whether the client is free. This site covers client installation and setup. Always follow applicable laws, network policies, and service terms where you are.

Clients, cores, and rules update separately

Community maintenance can bring interface changes, compatibility fixes, and new features. Client upgrades, core updates, subscription refreshes, and rule data updates are separate operations. A subscription refresh changes connection configurations; a rule data update affects classification; a core update may change parameter support; and a client upgrade may alter the interface or how configurations are generated. When an issue occurs, first note which of these changed most recently, then decide whether to restore previous settings or import the configuration again.

Before updating, keep the configuration you need and protect sensitive information in backups. Afterward, verify startup, subscription loading, connection, and routing in that order—don't just check whether the window opens. If a guide's menus don't match your version, look for the corresponding options by function, such as subscription management, system proxy, or routing settings. For platform-specific instructions, see the complete installation guides. To compare which of the three apps suits your needs, see the client comparison.

Setup guides and Troubleshooting

Once the basic connection works, choose a guide for the issue you're facing. Change one setting at a time and keep test results you can reproduce.

Browse all articles →
Troubleshooting

v2rayNG battery drain: Android background and battery settings

Find common causes of excessive v2rayNG battery use, compare battery consumption in VPN and proxy-only modes, and learn how to allow background activity on different Android brands. Check background activity and when disconnections occur before changing keep-alive settings, rather than disabling every battery restriction at once.

Read article →