desktop client / configuration guide

V2Ray for Linux Download & Setup

Start by importing a subscription, then configure the system proxy and routing in order.

protocols
  • VMess
  • VLESS
  • Trojan
  • Shadowsocks
Core
Xray / V2Fly
Client
3
Platform
4

download

Choose a platform,download a client

Use v2rayN on desktop and v2rayNG on Android. Check your operating system and CPU architecture, then choose the matching installer on the download page. Similar client names do not guarantee the same package format or core support.

Windows

v2rayN / Desktop · WPF

The cross-platform edition uses a modern interface, while the classic WPF edition retains the familiar Windows desktop experience. Both let you manage subscriptions, select an active server, and configure proxy settings. Choose based on your system requirements and interface preference; you do not need both editions to import the same subscription.

After the first launch, check that the server list and logs look normal before enabling the system proxy. If your browser works but a developer tool cannot connect, check that tool’s own proxy settings. Confirm these separately: the app launches, the core runs, and application traffic reaches the proxy.

Go to downloads →

macOS

v2rayN / Apple Silicon · Intel

Check your chip under About This Mac. Apple Silicon uses arm64; Intel uses x64. Choosing the disk image by processor is more reliable than guessing from the computer’s appearance. After installation, launch the app from Applications and follow any prompts for permissions required to open it for the first time.

After importing a subscription, test in a browser with the system proxy before trying other traffic-capture methods. Terminal tools may not use the desktop’s network proxy settings, so configure their proxy address separately. Note the original values before changing system network settings, and check that the proxy is restored when you quit the client.

Go to downloads →

Android

v2rayNG / Xray · v2flyNG / V2Fly

v2rayNG is the recommended starting point on Android; use v2flyNG when your configuration requires the V2Fly core. Most recent phones can use arm64. If you’re unsure about your device’s architecture, check the package details on the download page first. The apps differ in their cores and options, so a share link importing successfully does not guarantee full compatibility.

For the first connection, approve the system VPN prompt. The server configuration sets connection parameters; per-app routing determines which apps are covered. These are separate controls. If the connection drops in the background, check battery optimization and background restrictions, then review the logs for actual connection errors.

Go to downloads →

Linux

v2rayN / deb · rpm

Debian and Ubuntu distributions generally use deb packages, while Fedora and similar distributions typically use rpm. Choose the correct architecture too: x64 or arm64. Matching the package format is only the first step; check that your desktop environment and runtime dependencies meet the requirements. GUI clients must be launched from an available desktop session.

Linux desktop proxy settings and terminal environment variables are independent. First test connectivity through the local SOCKS port, then configure the desktop network proxy. If you need TUN, check permissions, routes, and DNS. Testing each layer separately helps distinguish desktop configuration issues from a server problem.

Go to downloads →

The download page lists packages by platform, with notes on compatibility. Once you’ve chosen an installer, return to the quick-start guide to import your configuration; there’s no need to look for a specific file on the homepage.

Browse all clients →

features

Configuration guide,five key settings

Subscriptions provide configuration; proxy modes control how traffic enters the client; routing determines its exit. Understand these three layers first, then enable TUN or switch cores if needed. The illustrations below show common settings; names and available features vary by client.

Subscription groups and server updates

A subscription link retrieves server configurations in bulk and is useful when connection details need regular updates. In v2rayN, create a subscription group, enter and save the URL, update the group, then select an active server. Unlike importing share links one at a time, groups make sources easier to distinguish and update or disable individually. Updates usually refresh the server list; they do not necessarily sync all local routing rules. Save any settings you need before deleting or overwriting a group. Subscription URLs may contain access credentials, so avoid exposing them in public screenshots, logs, or shared documents.

  • Subscription group: label and URL
  • Update subscription: confirm the list refreshes
  • Active server: select one before connecting
See how to import a subscription →
v2rayN Subscription Group Settings
Subscription GroupsGeneral
RemarksEveryday use
Auto-update intervalSet as needed
Enable updates
CancelOK

Example: save the group first, then update it from the Subscription menu.

quickstart

First connection,three steps

Installing the app does not finish the setup. Follow three steps: import a configuration, choose an entry point, and verify the connection. Tackle one kind of issue at each step so you can keep track of what is already working if something fails.

01 / import

Import a subscription and select an active server

Start with a valid subscription URL or share link. In v2rayN, create a subscription group, save its URL, and update it. In v2rayNG, add a source in subscription settings and update the configuration. Pasting a URL into a field alone does not complete the import: return to the list, confirm the configuration appears, and select the server you want to use.

Check that the protocol, server port, transport, and security layer match the configuration provider’s instructions. Do not use a regular web page URL as a subscription URL, and do not delete every group when an update fails. First identify the error: is the URL unreachable, the content unreadable, or the list empty after import? Then decide whether to change the update method or check the configuration source.

Subscriptions and single-server share links differ in scope: subscriptions typically refresh multiple server configurations, while a share link imports one configuration. The client does not provide a remote server account, and installing the software does not create a connection service. You need an existing configuration to continue.

Subscription import instructions →

02 / connect

Choose a proxy entry point, then a routing mode

On desktop, enable the system proxy first so apps that follow system settings can connect through the local listening port. On Android, approve the VPN prompt when starting the connection. Then choose a routing preset for your needs. Routing changes the exit decision; it does not replace the step of connecting apps to the proxy.

For everyday browsing, start with a common routing preset and test access to both local resources and remote sites. Developer tools, terminal apps, and some standalone applications may ignore system proxy settings; configure the proxy type, address, and port in their own settings. Unless you have a specific need, there’s no reason to enable TUN or layer multiple custom rules from the start.

The local listening address is usually a loopback address. Only consider widening the listening scope and changing firewall settings if you need to provide proxy access to other devices on the same local network. Allowing connections from the local network is not required for ordinary use on your own device.

See how to choose a mode →

03 / verify

Test web access, DNS, and app traffic

Start by opening a test website in your browser, then check the client logs for the corresponding connection. If the tool offers a connection test, use it as a helpful signal—but a successful test does not mean every app is using the proxy. Verify real application traffic, domain resolution, and the system’s traffic-capture scope separately.

If a website won’t load, first check the system time, server configuration, and local port, then check the system proxy, DNS, and routing. If the browser works but the terminal doesn’t, check the terminal’s proxy settings first. If domain names fail but connecting by IP works, focus on the DNS resolution path. Change one setting at a time and record the result before continuing; changing several at once makes the cause harder to identify.

Once the connection is verified, organize your everyday setup: keep the subscription groups you use, note your preferred routing mode, and understand what happens to system network settings when you quit the client. The same checks can help after an update or network change—there’s no need to reinstall from scratch.

Troubleshoot connection issues →

ecosystem

Open-source ecosystem,clients and cores

V2Ray is not the name of a single graphical app. Understanding how Project V, V2Fly, Xray, and the three clients relate can help you choose the right program for a configuration and identify which layer is causing an issue.

Project V: from proxy core to graphical client

Project V brings together a modular ecosystem of proxy tools, with V2Ray as one of its widely used core projects. The core combines inbound and outbound connections, routing, and protocol handling; graphical clients organize these capabilities into subscription groups, server lists, and settings. When you click Connect, network requests are usually handled by the core launched or integrated by the client—not by the interface itself.

This also explains why a configuration labeled V2Ray may behave differently across clients: import parsing, the way a client generates configuration, and the parameters supported by its core can all affect the result. When troubleshooting, distinguish between whether a link imports, whether the core starts, and whether the target request succeeds. These are three separate stages, not a single connection status.

V2Fly and Xray: related, but distinct implementations

V2Fly continues the community development of V2Ray, while Xray is a core project developed from related technology. They share technical roots but have evolved their protocol capabilities and configuration behavior independently. Names such as VMess, VLESS, and Trojan identify protocols; WebSocket describes a transport; TLS and REALITY relate to the security layer. These terms are not interchangeable.

Choose a core based on the requirements of your actual configuration, not just the project name. For example, if you use specific extension parameters, confirm that the core supports that combination. There’s no reason to change security settings in a standard configuration just to switch cores. A protocol alone does not determine speed: network path, server resources, transport, and client environment all affect performance.

Three clients: desktop management and Android use

v2rayN provides a graphical configuration interface for desktop use on the three platforms covered here. v2rayNG is for Android and uses the Xray core; v2flyNG is an Android client based on the V2Fly core. All three are open-source projects, but their interfaces, import support, and core integrations differ. Do not assume the menu steps for one client apply to another.

Open source means the source code can be viewed, used, and improved under the applicable license. It does not mean a client includes a remote proxy service or that every configuration can be imported. Evaluate the configuration source, app permissions, and device environment separately. For most users, choosing a client that fits the platform and protocol is easier to maintain than installing several clients and mixing their settings.

Licensing and updates: treat the interface, core, and rules separately

Clients, cores, and associated data may use different open-source licenses. Before using, modifying, or redistributing them, read the license terms for each project involved; a general “open source” label is no substitute for the actual terms. Community maintenance drives fixes and ongoing development, but whether an update suits your device still depends on system requirements and release notes.

For routine maintenance, distinguish what you are updating. Updating a subscription usually changes server configurations supplied remotely; updating the client may change its interface and configuration generation; updating the core may affect protocol behavior. Domain and IP category data belongs to another layer. If something changes, first identify what was updated, then check the logs before considering a rollback or reinstall.

Where to read next: If a website won’t load, use the Troubleshooting guide to check the entry point, DNS resolution, and exit. To keep server sources consistent across desktop and Android, read the multi-device configuration sync guide. Before writing custom routing rules, see the routing chapter. Going straight to the relevant topic makes it easier to find the cause than opening every advanced setting at once.

journal

Further reading, configuration and protocols

Once the basic connection works, move on to more specific configuration questions. These three articles cover protocol behavior, syncing across devices, and custom routing. Identify which layer your needs relate to, then choose the relevant approach.