v2rayNmacOS Download & Setup

V2Ray for Mac Download & Setup

From importing a subscription to system proxy, configure routing rules step by step and understand the config.json generated by the client.

  • VMess
  • VLESS
  • Trojan
  • Shadowsocks

CLIENT / PLATFORM

V2Ray Clients: Choose Your OS, Then Your Architecture

Use v2rayN on Mac, Windows, and Linux. For Android, start with v2rayNG; consider v2flyNG if you need its core. The client manages server details and local proxy settings, while the core handles connections. Installing a client does not provide a server. Before you begin, get a subscription URL from a trusted source or the complete server connection details.

Downloads are grouped by operating system. Don’t rely on a “desktop” label alone—check your device’s processor architecture and package format too. If you already have a configuration, back up your subscription groups, routing rules, and custom DNS settings before updating. For a fresh install, start with the defaults, establish a connection you can verify, then add rules one at a time.

Windows

v2rayN

Choose between the next-generation cross-platform desktop client and the classic WPF edition. Check the system requirements first, then select the interface that suits you. Menus may differ, but subscriptions, servers, and system proxy remain the main configuration areas.

After installation, add a subscription group and update the server list. If your browser uses a separate proxy extension, decide which tool should control its connection first. This helps avoid a setup where system settings have changed but the browser still uses a different route.

macOS

v2rayN

Check your chip under Apple menu > About This Mac. Choose the Apple Silicon download for an Apple chip or the Intel download for an Intel processor. After installation, move the app to Applications and launch it from there.

If a security prompt appears the first time you open the app, confirm the file’s source and follow the options in your system’s security settings. When troubleshooting connectivity, check the proxy status of the active network service too. Before quitting the app, make sure the system proxy has been restored.

Android

v2rayNG / v2flyNG

v2rayNG uses the Xray core and is the recommended starting point on Android. v2flyNG offers the V2Fly core. Choose the build for your device’s architecture, typically arm64 on newer devices; if you’re unsure, check which devices the universal package supports.

After importing a subscription, update it and select a server. Confirm the system VPN permission when starting a connection; other VPN apps may conflict with the active session. If the connection stops in the background, check battery optimization and background activity permissions.

Linux

v2rayN

Choose deb or rpm for your distribution, then select x64 or arm64. The graphical client is suited to desktop environments. After installation, make sure the app launches and the core loads before configuring desktop proxy settings or TUN permissions.

System proxy support varies across desktop environments. Browsers, command-line tools, and standalone apps may each use their own proxy settings, so opening a website in one browser does not mean every app is using the same connection route.

CONFIGURATION / WORKSPACE

v2rayN Settings and Configuration

Subscriptions determine which servers are available, routing decides which outbound handles each request, and system proxy or TUN determines which traffic reaches the core. These settings are related, but troubleshoot them separately. First check that servers load, then confirm the local traffic entry point, and finally review rules and DNS results.

These panels show setting names to help you find the corresponding options in the client. Menu labels may vary slightly between platforms and releases; use the current interface as your reference. Change one setting at a time and verify the result so you can identify what made a difference.

v2rayN / Subscription Group Settings

Servers

Subscription Groups

Settings

Subscription Group Settings
Remarks
Optional URL
Enable updates
Update subscription (without proxy)
Update subscription (through proxy)

A subscription URL fetches server configurations in one place, unlike a share link for a single server. In subscription group settings, enter the URL, save the group, and run an update to add its contents to the server list. Separate groups make it easier to manage different sources and identify which one failed to update. If the list is empty afterward, check that the URL is complete and the subscription is still valid, then try an appropriate update method. Unlike adding servers one by one, subscriptions can reflect changes from their source, but they do not sync all local routing settings.

Learn more: Import a subscription →

QUICKSTART / THREE STEPS

Import a Subscription, Choose a Proxy Mode, Verify the Connection

For your first setup, establish one clear connection path. Follow the v2rayN workflow on desktop and the subscription workflow in v2rayNG on Android. Their menus differ, but you can apply the same principles to connection details and verification.

Add a Subscription and Update the Server List

Start with the complete subscription URL. When copying it, make sure you don’t include spaces, line breaks, or explanatory text. In v2rayN, save the URL in subscription group settings and then run an update. In v2rayNG, add it from the subscription group section and update the subscription. For a single protocol share link, use the share-link import option instead of treating it as a subscription source and trying to update it.

Once the list loads, check the group, remarks, and protocol. A subscription URL may contain access credentials, so don’t include it in public screenshots or paste it into an unfamiliar online converter. If an update fails, check whether the error points to a malformed URL, a network issue, or a problem with the source’s response. Only after confirming the subscription source is reachable does it make sense to troubleshoot the proxy mode.

Select an Active Server and Set the Traffic Entry Point

Set the server you want to use as the active configuration, then choose system proxy or TUN. For an initial desktop test, system proxy is a good starting point because it avoids permission and virtual interface issues. On Android, confirm the VPN permission prompt when you start the connection. Routing determines where traffic goes after entering the core; it is separate from whether system proxy is enabled, and the two are not interchangeable.

If only one app cannot connect, check whether it uses system proxy settings or has its own proxy or DNS configuration. Don’t enable every traffic interception option to fix a problem in one app. If you need TUN, follow the guide to check permissions, routing, and local network access. If another network tool is already running, first determine which traffic each tool captures.

Check the Logs and Verify the Connection and Reset

Open a website you know is reachable, then check the client logs to confirm the core started and the request used the expected outbound. A test tool only reflects its target and network conditions at that moment; it cannot replace testing in the app you actually use. For split routing, test destinations that should go direct and those that should use the proxy, making sure broad rules haven’t overridden exceptions.

When testing is complete, disconnect and make sure your regular network access is back. If no websites load after stopping the client, check first whether the system proxy still points to a local listening address. If something goes wrong, note the error and the steps you took, then change one setting at a time. This makes it easier to tell a server issue from local traffic capture or DNS resolution problems than repeatedly switching servers.

PROJECT V / CORES / CLIENTS

The Project V, V2Fly, and Xray Ecosystem

The client manages configuration, the core handles connections, and protocols define how devices communicate. Understanding these three layers helps you identify compatibility, determine what an update affects, and locate problems.

Configuration Interfacev2rayN · v2rayNG · v2flyNG

Subscriptions, servers, proxy modes, and settings

Connection ProcessingV2Fly · Xray

Inbounds, outbounds, transports, routing, and domain resolution

How Project V and V2Fly Are Related

Project V is a useful starting point for understanding the technical background of V2Ray. V2Ray separates local traffic entry points, remote connections, and routing into distinct modules, which is why configuration files contain sections such as inbounds, outbounds, and routing. The V2Fly community continues V2Ray’s maintenance and development; its implementations are not the same thing as any particular desktop app.

When users save servers or change routing in the interface, the client typically translates those settings into a configuration the core can use. The window on the right shows a snippet of configuration fields to illustrate how inbound ports, outbound tags, and rules relate. It is not a complete, ready-to-connect configuration. A working connection also needs the server address, authentication details, and matching transport parameters.

Xray and Protocol Compatibility

Xray has technical roots in V2Ray and represents another core development path in the same proxy ecosystem. The two share concepts but also differ in features and configuration. Seeing the same protocol name does not guarantee that every transport, security option, or extension field is interchangeable. Check that both the client interface and the core in use support the options you need.

VLESS, VMess, Trojan, and Shadowsocks describe different connection methods. Whether they work depends on the server configuration and local implementation. A subscription can provide settings to a client, but it cannot make unsupported features available. When choosing a client, check your actual connection requirements first, then consider the platform and workflow; the core’s name alone is not enough.

What Three Open-Source Clients Do

v2rayN is an open-source desktop client for Windows, macOS, and Linux. It manages servers, updates subscriptions, and configures the local proxy. The desktop interface and core are separate components; check the relevant release notes to see which settings the interface supports and which cores it can use. Mac users can choose the installer for their chip, then apply the same subscription and routing concepts used on other platforms.

v2rayNG is an open-source Android client that uses the Xray core; v2flyNG is an open-source Android alternative using the V2Fly core. They share some workflows, but their menus, configuration support, and release schedules may differ. Each client has its own open-source license, and the licenses for the client, core, and bundled resources should be considered separately. One project name does not cover every component.

Updates and Preserving Configuration

Open-source projects are maintained by their respective communities, and client and core updates may happen independently. Updating the interface does not mean server settings have changed, and updating a subscription does not mean local DNS and routing rules have been carried over. Identify what is being updated first, then decide whether to export your configuration, restart the core, or recheck system permissions.

Keep a record of a working configuration, review setting changes before upgrading, and verify subscriptions, the active server, routing, and network recovery afterward. This site provides download links and setup guides, not servers or subscription services. Subscription validity, availability, and connection details are determined by their respective providers. Hide addresses, credentials, and personal information before sharing screenshots or configuration files.

NOTES / CONFIGURATION

Routing Rules, Multi-Device Sync, and LAN Sharing

Once the basic connection works, move on to multi-device setups and advanced network options. These technical notes tackle specific questions by explaining what each setting affects, then showing how to configure and verify it. Keep server details, client preferences, and system network settings distinct rather than treating them as one configuration.