Downloads / Choose your system, then your architecture
Choose a V2Ray Client by Platform
Use v2rayN on desktop, v2rayNG on Android, or consider v2flyNG when you need a V2Fly core. Downloading a client is only the first step: you still need a working server configuration. Installing a client does not provide a server or subscription. Identify your device first, then choose the right file on the download page to avoid architecture mismatches and reinstalling.
v2rayN is available as a desktop edition and a classic WPF edition. The desktop edition uses a cross-platform interface for managing configurations with a consistent workflow. The WPF edition retains the classic interface for users familiar with its menus and navigation. For both, check protocol support against your configuration and selected core rather than judging by appearance alone.
Before downloading, check your processor and system type in your system information. On first launch, verify the local listening port, import a known-good configuration, and then set up the system proxy. Avoid enabling system proxy control in multiple clients at once, as they may repeatedly overwrite the proxy settings.
v2rayN downloads for macOS are available for Apple Silicon and Intel. Check your chip or processor in About This Mac, then choose the matching architecture. Files for the same client are not interchangeable across architectures, and choosing the right one can avoid the overhead of a compatibility layer.
On first launch, follow the system prompts to grant any required permissions. After importing a configuration, test browser connectivity through the system proxy. Whether other apps use it depends on their proxy settings. If access fails, check the local port and proxy settings first rather than changing all your connection parameters at once.
For most users, v2rayNG with the Xray core is the first choice; use v2flyNG as an alternative when you need a V2Fly core configuration. Most devices use arm64. If you are unsure of your architecture, check the universal-build details. The client names are similar, but their core capabilities and supported connection parameters differ.
On first connection, approve the system VPN permission. Android restricts VPN access to one app at a time. Background connectivity can also depend on battery optimization, sleep settings, and network changes. Confirm the connection works in the foreground, then check background settings; this is more useful than repeatedly changing protocol fields.
v2rayN provides a desktop GUI for Linux. The download page primarily offers deb and rpm packages, including arm64 builds. Package management differs between Debian- and Ubuntu-based distributions and Fedora-based distributions, so check your distribution and processor architecture first. Package format is not the same thing as protocol type.
Not every app uses the desktop environment's system proxy settings. If your browser works but another app cannot connect, check that app's own proxy options. Set the client to launch at startup only after it connects successfully, so a misconfiguration is not carried into every login session.
Configuration overview / Tackle four issues separately
Subscriptions, Proxy Modes, and Routing Rules
Connection settings describe the server, proxy mode determines how apps connect, and routing rules decide where traffic goes. Checking these layers separately helps distinguish a client that has started from a proxy that is actually working. The settings shown below illustrate interface concepts; they are not a working server configuration.
Configuration / Import Options
Single Share LinkImport from Clipboard
Subscription GroupAdd Subscription URL
Update Configuration SetUpdate Subscription
Know which import option to use
A share link usually contains one server configuration; a subscription URL retrieves a set of configurations and supports future updates. Check what kind of link you have: import a single link from the clipboard or by scanning it, and add a subscription URL to a subscription group. Successful import only means the client recognized the content—it does not mean the server is reachable. Before updating a subscription, keep a copy of any manual configuration and check the updated node names, protocols, and transport parameters. Subscription URLs may contain access credentials, so do not share the full URL or screenshots that show it. If you need help, share only redacted fields.
The system proxy writes a local proxy address to the operating system settings, but each app decides whether to use it. Tun mode routes traffic through a virtual network interface, usually requires additional permissions, and may need routing and DNS configuration. For a first setup, test your browser with the system proxy, then decide whether Tun is necessary. Neither option is a protocol or a substitute for server configuration. If enabling one causes problems, disable the additional connection method and keep a simple test path. Then check permissions, ports, and conflicts with other network tools one at a time.
Routing rules send traffic matching a domain, address, or other connection condition to a specified outbound. Rules are usually evaluated in order, so put specific rules before broader ones that could override them. Start with a built-in client profile and add exceptions only for clear needs. Note your current profile before making changes, then test both proxied and direct destinations. Global proxy is also just a routing choice; it does not automatically capture traffic from apps that never connect through the client. DNS resolution location and results can affect rule matching, so check the logs as well.
Connection MethodApp proxy settings and listening port
AccessActual requests and logs
Test the connection with a real request
A successful port check only shows that a connection to the target port can be established; it does not confirm that the protocol handshake, authentication, and access to the destination will all work. After selecting a node, run the client's connection test, check that the system proxy points to the current listening port, then visit a site in your browser and review the logs. Do not rely on a tray icon or a single test result. If a test fails, identify whether it is a connection timeout, authentication error, or DNS resolution problem. Change one type of setting at a time and retest the same destination to see whether the change fixed it.
VMess, VLESS, Trojan, and Shadowsocks each make different design trade-offs. Real-world performance also depends on the transport, security layer, server load, and network path. Start with configuration compatibility, then compare them under the same conditions. A protocol name alone does not tell you how fast it will be.
Clients, cores, and rule data may update independently. Before upgrading, keep a working configuration and note which core and connection method you use. After the update, test your existing connection before enabling new features. This makes it easier to isolate compatibility issues instead of changing several layers at once.
Open-Source Ecosystem / Clients and Cores Have Different Roles
Project V, V2Fly, and Xray
V2Ray is a proxy software project in the Project V ecosystem. To understand how the ecosystem fits together, distinguish three things: the client provides the interface, the core handles connections and routing, and protocols define how systems communicate. You download a GUI client and choose a server configuration; the core called by the client actually handles the connection. These names do not have to match, and they are not interchangeable.
Graphical interface
v2rayN v2rayNG / v2flyNG
Import configurations, manage subscriptions, select nodes, and view logs.
→
Connection processing
Xray V2Fly
Protocol handshakes, transport handling, route matching, and outbound connections.
Project V's modular design
Project V divides proxy functions into modules such as inbounds, outbounds, routing, and transport. An inbound accepts connections from local apps; routing decides which outbound to use; the outbound then communicates with the remote server using the relevant protocol. GUI clients organize these concepts into menus and settings, so everyday tasks do not require starting with a full configuration file. When something goes wrong, tracing this flow is often more effective than reinstalling everything.
In everyday usage, V2Ray is also often used as a catch-all term for this type of client, but it does not refer to one specific GUI. When searching for the “V2Ray official site,” distinguish between the core project, client projects, and English-language information sites. This site provides download links and setup guides; clients do not include remote servers you can use out of the box. Connection settings must come from a working server you are authorized to use.
How V2Fly and Xray are related
V2Fly continues the community development of the V2Ray core, while Xray is a core fork developed from related code. The two share some concepts and configuration conventions, but their features evolve independently. A configuration that imports successfully is not necessarily compatible with both cores. Check the selected core's support for the specific protocol combination, transport parameters, and security layer.
For example, REALITY is a security-layer feature, not a standalone client at the same level as proxy protocols. For configurations that use it, check whether the client recognizes the fields, whether the core supports that combination, and whether the server settings match. Sharing a protocol name does not mean that ports, server names, public keys, or other fields can be mixed and matched.
What the three open-source clients do
v2rayN is a desktop client with GUI tools for server lists, subscription groups, system proxy settings, and routing. The cores it can use depend on the release and its settings. v2rayNG is an Android client that uses the Xray core; v2flyNG is also for Android and uses the V2Fly core to process configurations. Choose by operating system first, then check which features your server configuration requires.
All three clients are open-source projects, so their public source code can help you understand how features work and how they change. Open source describes access to and licensing of code; it does not mean that separate projects follow the same maintenance schedule. GUI clients and the cores they include may also use different licenses. If you redistribute or modify them, review the license and notices for each component separately.
Update mechanisms and configuration compatibility
Client updates may change menus, import parsing, permission handling, or how cores are invoked. Core updates may change protocol implementations or configuration requirements, while rule data updates can affect domain categories and routing matches. Treating these as changes to separate layers helps pinpoint where a connection broke after an update, rather than assuming the server configuration is at fault.
Subscription formats also vary. A subscription URL may return a set of share links or a complete configuration in a particular format, and clients can only process formats they support. If an import fails, first confirm the format and what the URL returned, then check that the URL is complete and its access credentials are valid. A subscription URL is not a browser proxy address, and manually edited node settings should not be assumed to persist through subscription updates.
Once you have imported a basic configuration, explore the guides that address your needs. Protocols focuses on configuration capabilities, the Ecosystem section explains the difference between clients and cores, and Platforms covers installation, system proxy settings, and startup. Keep your working settings as you go, and verify after each change to avoid combining multiple issues in one troubleshooting session.
Install the v2rayN desktop client from deb or rpm packages on Debian/Ubuntu- and Fedora-based distributions. Configure desktop autostart and the system proxy, and troubleshoot common dependency issues.
Check your distribution and architecture first, then launch the app manually and verify a connection. This guide treats installation, desktop sessions, and proxy settings separately to help diagnose cross-layer issues, such as an app that launches but does not route traffic through the proxy.
Explore the origins of Project V, how the V2Fly and Xray core branches differ, and which cores and platforms are used by v2rayN, v2rayNG, and v2flyNG.
Look beyond the client interface to the components that actually process connections, and learn why a successful import does not guarantee core compatibility. Build a solid foundation before switching clients, migrating configurations, or interpreting protocol settings.
Compare the design, encryption, and resource trade-offs of four proxy protocols, with practical guidance for desktop use, battery life on mobile devices, and sharing across multiple devices.
Transport and security layers also affect handshakes and resource use. This guide examines each factor separately so you don't mistake a newer name, extra parameters, or a single test result for a universal performance ranking.