Open-source clients and setup guides

V2Fly Official Sitev2rayN Client

Choose an open-source client for your device, start by importing a subscription, then configure routing and test the connection.

Protocol
  • VMess
  • VLESS
  • Trojan
  • Shadowsocks

Choose an installer for your device

Use v2rayN on desktop; on phones and tablets, choose between v2rayNG and v2flyNG. First identify your operating system, then check your processor architecture—installation methods vary by platform. When switching devices, you can import the same subscription URL again; there’s no need to copy the old device’s port, proxy mode, or rules.

Windows

Choose the cross-platform desktop edition or classic WPF. If you follow an older guide, check that its screenshots match your edition.

Before moving a portable install, quit the app, back up your settings, and note the local port. Running both copies can cause a port conflict.

Go to downloads

macOS

Check About This Mac and choose the Apple Silicon or Intel installer. After installation, open v2rayN from Applications, not the disk image.

If your browser bypasses the client, check both its proxy settings and the network service’s. If browsing breaks after quitting, restore your original network settings and retry.

Go to downloads

Android

Start with v2rayNG (Xray), or choose v2flyNG if your setup requires the v2fly core. Most recent phones use arm64; check the universal package if unsure.

Look for the VPN permission prompt on first connection. Another VPN app may replace the connection. For screen-off drops, check background and battery settings first.

Go to downloads

Linux

Choose deb for Debian or Ubuntu and rpm for Fedora. Check architecture separately: either format may offer both x64 and arm64 packages.

Desktop apps and command-line tools may use different proxy settings. If only one app fails to connect, check its settings before reinstalling v2rayN.

Go to downloads

v2rayN settings

Subscriptions update the configuration list, routing determines where requests go, and the system proxy and TUN determine which requests enter the client. Check these separately to pinpoint issues more easily than by changing several settings at once.

Create a separate group for each subscription source and give it an alias that identifies the source. After pasting the URL, update the group manually and confirm the list has populated before enabling scheduled updates. Groups make it easier to see which source changed than importing links one by one, but a successful update only means the client read the configuration—it doesn’t guarantee that every entry can connect. If the list is empty, check that you selected the right group, then verify that the subscription URL is still valid and returns content the client can read. Hide the full URL when sharing screenshots.

Project V, cores, and clients

Documentation often uses “V2Ray” as shorthand for the client, core, and protocol. Keep these three layers separate when troubleshooting: the interface manages settings, the core reads them and establishes connections, and the protocol defines how the two ends exchange data. Identify the layer that’s failing before deciding what to change.

Compare the three clients →

Project V and V2Fly

Project V is a good starting point for understanding the ecosystem. V2Ray is its core program for handling proxy connections and routing. The V2Fly community continues to maintain related core software and documentation, while desktop and mobile graphical clients are maintained by their own projects. When following core documentation, don’t expect to find every field under the same name in a graphical interface: a setting may appear under subscriptions, routing, or transport—or may not have a dedicated control at all.

To check whether documentation applies, first see whether it describes a graphical interface or core configuration, then check that its operating system and core family match yours. For example, an inbound port in core documentation is where the client receives requests on your device; it isn’t the remote server’s port in a subscription. Confusing the two can make websites appear unreachable, but the relevant logs differ. For the former, check the local listener first; for the latter, review the connection settings.

V2Fly and Xray compatibility

Xray originated in the V2Ray ecosystem and has since been developed independently. The two core families share support for some protocols and configuration concepts, but each also has its own transport and security features. Configuration names alone don’t tell you whether a setup is compatible: two configurations using the same protocol may still use different transports or require different security fields. Keep the original parameters from the subscription and choose a core based on the provider’s documented combination. Don’t piece together settings from another connection.

If apps still can’t connect after you switch cores, check the first error in the startup logs. An unrecognized field usually points to a compatibility issue; a local address that can’t be bound usually means the port is in use. Check remote connectivity and the handshake only after confirming that the core started successfully and requests are passing through it. This helps distinguish failures at three different stages instead of attributing them all to an expired subscription.

Protocol names and connection requirements

Open-source clients and cores make their configuration fields and protocol implementations available for inspection. VMess, VLESS, Trojan, and Shadowsocks are protocol names, not interchangeable options for any configuration. A connection works only when both ends agree on the protocol, transport, and required security settings. In particular, VLESS isn’t an encryption method; check the specific configuration to determine which security layer it uses.

For your first connection, use the original combination provided with the configuration as a baseline. If the handshake fails, first check the address, port, transport, and security settings, then verify the device’s clock. Switching protocols requires the other end to provide a matching configuration; changing one client setting can’t convert an existing connection to a different protocol. To find an option that fits your device, first compare core support, then consider your network and device requirements.

What sets the three open-source clients apart

v2rayN brings desktop subscription, routing, and proxy settings together in a graphical interface. v2rayNG is a mobile client built primarily around the Xray core and routes traffic through the system VPN interface. v2flyNG is another open-source graphical client for configurations that specifically require the v2fly core. Choose based on what your device can run and what core your configuration requires—not on similar names or icons.

When using the same subscription across devices, import it again and check the proxy setup for each platform. Desktop system proxy settings don’t carry over to a phone, and VPN permissions and per-app settings on a phone don’t carry over to a desktop. If only one device connects, select the same configuration on both and compare the core and network environment. Matching group names don’t prove that both devices are using the same connection.

Clients, cores, and subscriptions update separately

Client releases, core updates, and subscription refreshes are three different things. A client update may move menus or change installation requirements; a core update may change which fields it recognizes; refreshing a subscription rereads the configuration list from its original URL. Back up your groups, routing rules, and other settings before replacing an installer. After updating, test one change at a time: first confirm the program starts, then test a known working configuration, and finally restore your custom routing rules.

If an issue starts right after an update, note when it happened, which platform you’re using, and what action triggered it, then collect the relevant logs. When sharing a log excerpt, include the first error and a few surrounding lines. Remove subscription URLs, identity parameters, and any destination addresses you don’t want to share. If only one subscription group is affected, check that group’s update results; there’s no need to delete other groups that still work. Visit the help center →

Technical notes

Choosing a client, troubleshooting, and installing each call for a different checklist. If a connection is established but one app misbehaves, start with the logs. If the client isn’t installed yet, follow the first-install checklist. Compare protocols only after confirming that both the configuration and the client support the same set of protocol settings.

Choosing

VMess, VLESS, Trojan, and Shadowsocks compared: differences and use cases

Compare four proxy protocols across encryption, handshake overhead, transport options, and client compatibility, with recommendations for everyday browsing, mobile networks, and lower-powered devices.

Key takeaway: Narrow down the options by finding a client and server combination that works, then compare how each handles changing network conditions.

Troubleshooting

How to read V2Ray logs: common errors and step-by-step troubleshooting

Learn how to open client logs, adjust the log level, and interpret common errors such as handshake failures, connection timeouts, port conflicts, and clock mismatches—with a troubleshooting sequence that starts close to the source.

Key takeaway: Find the first failure by timestamp and distinguish startup, DNS resolution, and handshake errors. Don’t focus only on the last line.

Getting Started

v2rayN first-install checklist: essential steps and common pitfalls for Windows and macOS

A step-by-step guide to v2rayN’s first-run settings, including the extraction folder, runtime requirements, core selection, local port, system proxy, and subscription import—plus common beginner pitfalls.

Key takeaway: Get one connection working first. Confirm the port and proxy mode in use before adding custom rules.