V2RAYN · V2RAYNG · V2FLYNG

V2Ray for Macv2rayN Downloads & Setup

Choose an open-source client for your device, then follow the guides to import subscriptions and configure routing.

Xray V2Fly JSON Config
Client directoryFind by operating system

V2Ray Client Downloads

Start by checking your device's operating system, then confirm the CPU architecture and package format. Installing the app and running the subscription's configuration with a compatible core are separate steps. Get the app installed first; after importing nodes, check the protocol and transport settings.

First-time setup & migration

Moving from an older device? You don't have to copy every custom rule first. Note the client you use, subscription source, core type, and active routing policy. On the new device, import a group of nodes and test one known-good node as a baseline before restoring other rules. The old device's system proxy address, port, and LAN access settings may not suit the new one.

If installation fails, identify where the error occurs. If the installer won't open, check the CPU architecture and package format. If the app opens but the core won't start, review the startup log. If only one node fails to connect, check its protocol and parameters. This keeps installation issues from being mistaken for an expired subscription—and avoids reinstalling the whole client to fix one node.

Browse all clients →

Setup sequence

From subscription import to proxy

First get the core working with one node, then check which apps send traffic through the client. Each of the five steps below can be read on its own. The fields and settings on the right are examples for matching the interface and reading logs, not a complete, ready-to-run configuration.

Keep subscription groups separate

Add the subscription URL to its own subscription group, then update it manually once. After the update, check that nodes appear and confirm their protocols and labels. Unlike importing a single node from the clipboard, a subscription group records the source for future updates, keeping provider changes separate from your own notes. If the list is empty, check the URL, its expiration, and whether the client can read the response format; there's no need to change the system proxy yet. Subscription links may contain access credentials, so hide the full URL in screenshots and support requests.

See how to import a subscription

Subscription group settings
Update current subscription
Import multiple URLs from clipboard

Projects & maintenance

Project V, V2Fly, and Xray

The app name on a download page, the protocol name in a subscription, and the core name in a log refer to different layers. Distinguish them to tell whether you need a different installer, a different core, or just a parameter change. This handbook covers client downloads and configuration; each project's maintainers handle development and releases for their clients and cores.

Project V and the origins of V2Ray

Project V is the name of a proxy-tool ecosystem, and V2Ray is its core program for handling and forwarding connections. Its configuration separates inbound, outbound, and routing sections: inbounds receive connections, outbounds determine how they leave, and routing chooses the path between them. GUI clients organize common settings into forms and can generate configuration from the selected nodes and rules. As a result, what you see in the interface may not exactly match the configuration that runs.

When reading an older guide, first identify whether it describes an interface action or a core field. For example, opening “System Proxy” sends app traffic to a local inbound; routing.rules in a configuration is used only after the core receives traffic. Changing the system setting doesn't prove that a routing rule matched. Conversely, even a correct rule can't handle traffic from an app that never used the proxy. These boundaries are a more reliable way to isolate the issue than following an old screenshot and checking boxes one by one.

How V2Fly and Xray diverged

The V2Fly community continued maintaining V2Ray. Xray forked from V2Ray and has evolved independently, adding features such as REALITY and XTLS Vision. The two retain some similar configuration structures, but fields, protocols, and transports with the same names aren't necessarily interoperable. When migrating, check the server or subscription documentation for the required protocol, transport, and security layer. Then review the client startup log to confirm that the running core supports that combination.

A protocol defines how the two ends exchange data; a transport determines how protocol messages are carried; and a security layer has its own handshake and authentication requirements. For example, seeing VLESS in a node doesn't tell you which client to choose—you also need to know whether it depends on a particular security layer or flow control. If the configuration is rejected before startup, check which fields aren't recognized. If it loads but the handshake fails, compare the server-provided parameters one by one. Both errors can look like connection failures, but they require different fixes.

What three open-source clients are for

v2rayN is an open-source desktop client that brings subscription management, node selection, and local proxy settings together in one interface. v2rayNG is an open-source mobile client that uses the Xray core; v2flyNG is also open source and supports configurations that require the V2Fly core. Open-source licenses define how code can be used, modified, and distributed. Check the license for the specific project and release; a client's license terms aren't interchangeable with those of its core or other dependencies.

Before switching apps, make sure the issue is actually a core difference. For example, if a computer connects but a phone only works in the foreground, first check VPN permission and background activity restrictions. If only some domains fail on the same device, check DNS and routing. Switching apps may also change default routing, ports, or traffic capture. Without repeatable tests, you can't tell whether the connection came back because the core changed or because the original system settings were reset.

Updates to clients, cores, and rules

A client update may change the interface, packaging, or configuration generation; a core update may change supported fields, defaults, or log output; and updates to geodata or site rules may change which traffic a routing rule matches. These updates don't necessarily ship together. When reporting an issue, say whether the change involved the app, core, subscription, or rule data so the new behavior can be compared with the relevant update.

If your configuration uses custom inbounds or routing, save a local backup before updating and note a connection you can use for testing. After the update, check that the core starts, then verify local listening, handshakes, DNS resolution, and routing. In particular, don't rely on a single node speed test to validate internal work domains or services that must connect directly. For configuration field details, see the JSON handbook.

Installation & connection FAQ

For a first-time setup, start by identifying which layer the problem is in. Use the questions below as a troubleshooting sequence.

The subscription imported successfully. Can I use it right away?

Seeing nodes in the list only confirms that the client read the subscription. After selecting a node, make sure the core starts successfully and send a request from an app that uses the local proxy. If the client can run a speed test but the browser shows no traffic, check whether the browser uses the current system proxy; there's no need to import the subscription again. If nodes are listed but startup reports a field error, check core compatibility rather than changing DNS. See the import and testing steps.

Are the system proxy and V2Ray global proxy the same switch?

No. The system proxy determines which local address apps that honor it connect to; global routing generally determines which outbound policy handles traffic entering the core. If an app connects directly, the core's global rules never see that connection. See how proxy traffic is routed.

The connection works, so why won't some domains load?

In the same app, compare one accessible domain with one that fails. Check whether each resolves, matches the expected rule, and uses the intended outbound. Keep the node and network unchanged while testing; adjust one setting at a time. Test each step in the guide.

Can I copy the old device's configuration as-is?

Move the subscription and only the rules you need, then check the core, listening address, port, and system proxy against the new environment. Don't assume the old device's network adapters, LAN addresses, or exception list are suitable defaults. See the client setup sequence.

Field notes

Core selection & connection troubleshooting

Troubleshoot by symptom: if the node errors as soon as it starts, check the core and fields first. If the core is running but the node times out during testing, check connection requirements. If the node passes its test but pages still won't load, first confirm that the app is sending requests to the local proxy.