Open-source clients · Setup guides

V2Ray Community v2rayN downloads

From choosing a client to importing subscriptions and configuring routing, find the right download for your OS, then use the same checklist to verify where your traffic goes.

  • VMess
  • VLESS
  • Trojan
  • Shadowsocks

01 Settings

V2Ray Client Features

Subscriptions provide configuration; system proxy or TUN determines how traffic reaches the client, and routing decides where it goes. Here’s how each setting works.

Subscription URLs and individual share links

Your service provider gives you a subscription URL to fetch and refresh a set of configurations. An individual share link usually contains just one connection configuration. In v2rayN, give each subscription group a clear name, save its URL, then update the group. Compared with pasting links one by one, groups make it easier to trace where entries came from and keep temporary test connections separate from your regular list. After updating, check that entries appear, then select one to connect. An imported entry isn’t proof that the connection works.

  • Before changing a subscription URL, make sure you’ve selected the right group.
  • Redact the full URL in screenshots; the path itself may be used for authentication.
Example subscription URL · domain retained, not usable
https://example.invalid/list

For an individual link beginning with vmess:// or vless://, use the share-link import option.

02 Choose a package

Download a client for your OS

Check your operating system first, then confirm the processor architecture or package format. The same app name doesn’t mean two devices can use the same installer.

Windows

The desktop and classic WPF editions are both called v2rayN. If this is your first install, start with the desktop edition. Choose WPF if your guide uses the classic interface or you already know the older menus. Before downloading, check your system type in the OS “About” page; don’t infer the architecture from the OS name alone.

If you downloaded an archive, extract all its files to a directory your account can write to, then launch it from there. Running it from the archive preview may start the main program without the files it needs alongside it. If you already have settings, back them up before testing in a new directory. Once you’ve confirmed your subscriptions and routing are intact, you can remove the old directory.

Go to downloads

macOS

Open About This Mac from the Apple menu. If it lists an Apple chip, choose the Apple Silicon package; if it lists an Intel processor, choose the Intel package. Download v2rayN and install it using the instructions in the disk image. Launch it from Applications rather than running it from the mounted image.

If macOS blocks the app from launching, check whether the warning concerns compatibility, its source, or permissions. Don’t disable system-wide protections for one app. Seeing the app in the menu bar doesn’t mean the system proxy is working. After changing the setting in the client, test with an app that follows system proxy settings, then configure your terminal separately if needed.

Go to downloads

Android

Choose v2rayNG if you need the Xray core; consider v2flyNG only if your setup specifically depends on the V2Fly implementation. Most recent devices support arm64; if you’re unsure which architecture your device uses, choose the universal package. A universal package solves architecture compatibility, not missing protocol support in another core.

When you open an installer from a browser or file manager, installation permission is usually granted only for that source and can be revoked afterward. On the first connection, the OS may ask you to authorize a VPN connection. If another app is already using that connection, disconnect it before testing. When importing, distinguish between a subscription group and an individual share link.

Go to downloads

Linux

For v2rayN, start with the package format commonly used by your distribution: Debian- and Ubuntu-based systems generally use deb, while Fedora-based systems usually use rpm. Then choose x64 or arm64. Confirm both before installing; an architecture mismatch and a missing runtime dependency are different issues.

Desktop proxy settings aren’t necessarily passed on to terminal tools or background services. If your browser works but a command-line tool times out, check the local listening address and port, the proxy types supported by the tool, and whether proxy environment variables are available to the current process. Once those are confirmed, check the client’s routing and outbound settings.

Go to downloads

03 Projects and cores

The Project V open-source ecosystem

Is a guide about the client, the core, or the server? Identify the layer first, then decide whether its instructions apply to your device.

From the user interface to connection handling
  1. ClientImports and edits configurations, then lets you choose one
  2. CoreAccepts inbound connections and selects an outbound by rule
  3. DestinationConnects directly or routes traffic through a proxy outbound, based on the match
  1. Project V: Why the client and core are separate

    Project V is a useful starting point for understanding this ecosystem. Early V2Ray focused on separating inbound connections, outbounds, and routing into composable configuration. Inbounds accept connections, outbounds send them onward, and routing selects between outbounds. This separation means the app initiating a connection, the core forwarding traffic, and the graphical interface managing configuration don’t have to be part of one program. Desktop and mobile clients developed by the community provide a more convenient way to work with these components.

    This history helps when troubleshooting. Seeing a subscription entry in the client only means the interface has data. To confirm the configuration loads, check the core’s startup result; to see whether an app’s traffic reaches the core, check how that traffic enters. Confusing these steps often leads to repeatedly importing a subscription when the real issue is that the app isn’t using the proxy at all.

  2. V2Fly and Xray: Shared roots, separate development

    The V2Fly community continued developing and maintaining the V2Ray core. Xray forked from that codebase, and the two projects have since evolved independently. They share similar configuration concepts, and some protocols and fields may look alike, but a shared origin doesn’t guarantee compatibility. In particular, one core may handle a newer transport or security-layer option differently from the other. Check what the server requires, then confirm which core your client is using.

    When moving to a new device, don’t assume you should copy over the entire configuration. The parameters for an individual connection, subscription groups saved by the client, and local listening ports and system proxy settings are separate layers. Start by moving a connection entry and testing it on the new device, then add routing rules back one at a time. If it fails, you’ll have a better chance of telling incompatible parameters from local settings that still need to be configured.

  3. Open-source licenses aren’t proxy protocols

    VMess and VLESS describe how two endpoints exchange data. Open-source licenses define how code may be used, modified, and redistributed. They address entirely different things. The V2Fly core uses the MIT License; Xray-core uses the Mozilla Public License 2.0. The MIT License has fewer redistribution requirements but still requires preserving relevant copyright and license notices. Under the MPL, obligations mainly apply to covered files; if you distribute changes to those files, you must make the corresponding source available under its terms.

    Components are maintained separately, so check their licenses separately too. Don’t assume the graphical client, bundled core, and other components share the same terms just because they came in one installer. You don’t need to read every license before setting up a client, but if you plan to repackage, modify, or publish a derivative version, review the license included with each component. Proxy service accounts, plans, and terms of use are set by the service provider, not by open-source licenses.

  4. How three clients fit different configuration needs

    v2rayN is an open-source desktop client that brings subscription groups, connection selection, routing, and system proxy settings together in one interface. It suits users who manage multiple configurations or need to troubleshoot traffic from different apps. v2rayNG is an open-source Android client that uses the Xray core; v2flyNG is also open source and uses the V2Fly core. You don’t need to install both just because their names look alike. Choose one based on the server parameters and the core it supports, test a basic connection, then compare the settings if needed.

    When describing an issue, include the app name, core, and steps that triggered the error. That’s more useful than a screenshot that only says “connection failed.” Did a subscription update fail to retrieve data? Did the core report an error after you selected an entry? Or does just one command-line tool bypass the proxy? Each points to a different place to check. When sharing logs, include timestamps, steps, and error types, but redact subscription URLs, account details, and sensitive server parameters.

  5. Client updates, core updates, and subscription refreshes

    A client update may change menus, installation, or how settings are stored. A core update may change supported fields or startup behavior. A subscription refresh simply fetches the latest entries from the provider. These changes aren’t interchangeable. Before updating, note the selected entry, core, routing mode, and local listening port. Back up any custom rules you need to keep. Change one layer at a time and retest with the same app and destination so you can tell what caused the difference.

    If every app stops working after an update, check whether the core started and whether the inbound is listening. If only one app is affected, check that app’s own connection settings. If a subscription refresh removes entries, confirm which group you updated and whether the provider actually removed them before overwriting local configurations. For step-by-step help, see the all-platform guide. If the connection works but traffic takes the wrong route, start with the routing and proxy articles in the Help Center.

04 Technical notes

Troubleshooting system proxy, routing, and subscriptions

Start with the symptom: a terminal that isn’t using the proxy, traffic sent through the wrong outbound, and hard-to-manage subscription groups are three different problems.

v2rayN system proxy not working? Fix browser and terminal proxy issues

Troubleshoot browsers and terminals separately: check whether the system proxy is set and whether a browser extension is taking over, then check terminal environment variables and the local port to find out why the v2rayN system proxy isn’t working.

Don’t reinstall the client yet. Browser extensions, system proxy settings, and terminal options may point to different endpoints. Find out which port the tool actually connects to before investigating forwarding. If a connection never reaches the client, changing its outbound or routing rules won’t fix the problem.