V2Ray User Guide: Installation & Configuration

01 / concepts

Core Concepts: Know Where Your Traffic Goes

The Client, Core and Server

V2Ray is a proxy technology ecosystem within Project V, not a desktop app. v2rayN provides a graphical interface for managing servers, subscriptions, routing and launch options; the core listens on local ports, processes requests and establishes remote connections. A client window opening normally only confirms that the interface is running—it does not mean the core started successfully.

V2Fly continues development of the V2Ray core, while Xray is part of a related core family. Their feature sets differ. A client may store the same node description for either, but whether that node works depends on the selected core. For VLESS, REALITY or specific flow-control settings, choose a core compatible with the server configuration. The protocol name alone does not guarantee compatibility.

The remote server is where traffic leaves the local proxy chain. Installing a client does not provide a server address, authentication details or a subscription. Verify your node source independently; this guide covers software configuration only. Connection problems can occur in the local app, along the network path or at the server. Troubleshoot each layer separately rather than assuming the client is always at fault.

Ingress, Routing and Egress

A typical request travels from an app to a local SOCKS or HTTP inbound, then the core applies routing rules to select an outbound—direct or proxied. The system proxy affects only apps that honor that setting. Routing rules apply to traffic that has already reached the core, so changing them won’t make an app that bypasses the proxy start using the client.

A node entry typically contains a server address, remote port, protocol, authentication details, transport and security settings. The local listening port is an inbound setting, not the remote port. Entering the server port in your browser’s local proxy settings—or putting the local port in the node address—sends requests to the wrong place.

“Connected” can mean several different things: the client has selected a node, the core process is running, a connection to the server has been established, or the target site has returned content. Each describes a different stage. One successful test does not prove every app is proxied; one inaccessible site does not mean the whole node is down. Pinpoint where the failure occurs before troubleshooting further.

Protocol, Transport and Security

VMess, VLESS, Trojan and Shadowsocks are proxy protocols; TCP and WebSocket are transport methods; TLS and REALITY involve connection security and handshake requirements. These options aren’t freely interchangeable. The client and server must agree on the required fields. Changing one often means changing the other end too—not simply ticking a box in the client.

Protocol names don’t translate into a speed ranking. Real-world performance depends on the route, server load, transport overhead, destination and local network. Check compatibility first, then compare stability under the same conditions. Disabling certificate verification or changing handshake parameters at random is not a normal performance tweak; first find out why those fields are required.

02 / clients

Choose a Client: Start with Platform and Compatibility

For Desktop, Start with v2rayN

Use v2rayN on Windows, macOS and Linux desktops. It brings node management, subscription updates, local inbounds and routing into one graphical interface, making it the focus of this guide. Cross-platform support doesn’t mean every system behaves the same: startup permissions, how system proxy settings are applied, virtual network adapter support and configuration storage all depend on the OS and installation method.

The Windows downloads include the Desktop edition and the classic WPF edition. Desktop uses a cross-platform interface; WPF retains the classic Windows interface. If you’re new, start with Desktop. If you already use WPF or rely on a specific configuration, compare the current interfaces and features first. Don’t let both editions manage the system proxy at the same time, and don’t share a writable configuration directory without a backup.

On macOS, choose the Apple Silicon or Intel installer to match your processor. Check About This Mac for your chip details. On Linux, consider both processor architecture and package format: most desktop PCs use x64, while some devices use arm64. deb and rpm are package formats, not indicators of core protocol support, and you can’t install one by simply renaming it to the other.

Android vs. Desktop

On Android, start with v2rayNG. If you need the V2Fly core, consider v2flyNG. Recent mainstream devices usually use arm64; if you’re unsure of the architecture, a universal package may work, but check what your device supports. Successful installation doesn’t guarantee full compatibility: architecture determines whether the app can run, while node protocol support and OS restrictions require separate checks.

Android clients typically route traffic through the system VPN service, so you’ll see a system permission prompt at startup. Don’t assume Android VPN routing works like a desktop system proxy just because the buttons have similar names. On Android, check battery optimization, background activity restrictions and conflicts with other VPN apps. On desktop, common issues include port conflicts, insufficient permissions and apps that ignore the system proxy.

You can import a subscription from the same source on desktop and Android, but the clients may not support every field in it. If a node works on one device but not the other, compare the parsed protocol, transport, security settings and core capabilities before assuming the subscription is broken. Check subscription contents, client settings and OS-level traffic handling separately; copying between devices doesn’t remove the need to do so.

Download After Choosing

You don’t need to install all three clients. Start with one and establish a stable baseline; try another only when you have a specific compatibility need. Switching frequently adds variables, and system proxy settings or background processes left by an old client can interfere with the new one. For a device you rely on, keeping a recoverable setup is more useful than constantly changing interfaces.

The downloads page organizes installers by platform. Before opening it, note your OS, processor architecture and package format. After downloading, continue to the installation chapter. When migrating from another client, record your local inbound ports, routing choices and subscription groups too; standard node share links may not include them, so save them separately.

03 / installation

Installation Checks: Startup and Listening Ports

Complete the OS Installation

On Windows, follow the installer prompts to choose a folder and complete setup. On first launch, check that the interface and logs look normal. The classic and Desktop editions may store configuration in different locations; don’t overwrite files based on folder names alone. If the installer asks for an additional runtime, follow the current prompt rather than guessing from an old guide. Don’t run multiple instances that compete for the same listening port.

On macOS, open the disk image that matches your chip and follow the prompts to move the app into Applications. If macOS displays a security warning, verify the source and understand the reason before allowing the app to open. Permanently lowering system security is not a general installation step. When upgrading, quit the old process first, then launch the new app and confirm where it reads its configuration.

On Linux, open the deb or rpm package with your distribution’s graphical installer; the relevant package manager handles dependencies. After installation, launch the app from the application menu and check the interface, configuration directory and logs as a regular user. Grant extra permissions only when a feature requires them. Running the entire graphical client with elevated privileges long-term expands the permissions available to its configuration files and network operations.

On Android, open the package using an installation method allowed by your system. On first launch, import a node, then approve the VPN permission. If Android says the app wasn’t installed, check the architecture, available storage and whether an older app with a different signature is installed. Export any configuration you need before uninstalling; removing the app may delete its data. Reinstalling shouldn’t be your first troubleshooting step if you have no backup.

Check the Core and Listening Address

Once the client interface is open, check the logs to see whether the core started. Without a valid node, the client may not start the proxy service. If you see an error, address the first relevant log entry before testing the network. A port conflict, invalid configuration syntax and an incompatible core are different problems. Repeatedly clicking Connect won’t change those conditions and can make the logs harder to read.

For a local inbound, use a loopback address such as 127.0.0.1. It accepts requests from the same device and is a good default. “Allow connections from LAN” expands who can access it and requires appropriate firewall rules and access controls. Don’t expose it on every network interface just to get a browser working on your own machine; a local connection failure usually isn’t a LAN permission issue.

ss -tlnp
ss -tlnp 'sport = :10808'

The first command lists TCP listeners on Linux; the second checks only the example port. Process names may be missing if you don’t have sufficient permissions, but you can still confirm whether an address and port are listening. If nothing is listening on that port, check the client’s actual settings and startup logs. If another process is using it, identify that process before changing the client port or stopping the conflicting service.

Set a Post-Installation Baseline

For the first check, use just one traffic-handling method—don’t enable both the system proxy and TUN. Import a valid node, verify the core with a tool that explicitly uses the local proxy, then test the system proxy. This separates “nothing is listening” from “the app isn’t using the proxy.” Turning on several modes at once makes it hard to tell which setting caused the result.

Installation is complete when the interface opens, a valid configuration starts the core, the local inbound listens, and network settings can be restored after you quit. Don’t rush into complex routing. Keep this simple baseline so you have a reliable point of comparison as you add features.

04 / subscription

Import Subscriptions: Groups, Updates and Node Checks

Subscriptions vs. Share Links

A subscription URL points to an updatable collection of nodes; a node share link usually describes just one. Check the source’s instructions before choosing an import method. Trying to parse a subscription URL as a single-node link—or pasting a node share link into the subscription field—can leave you with an empty list. Switching proxy modes won’t fix the mismatch.

In v2rayN, open the subscription group settings, add a group, enter a name and the full URL, then save and update that group. Names based on purpose or source make update errors easier to track down. Query parameters often provide access credentials, so copy the entire URL without adding line breaks, quotes, trailing punctuation or extra spaces from a chat app.

Treat subscription URLs as sensitive information because they may contain access credentials. Hide the full URL in screenshots and check for query parameters before sharing logs. A subscription can deliver node configuration, but it doesn’t prove the source is trustworthy. Check the contents and source of unfamiliar subscriptions, QR codes or configuration files before importing them into a client.

A Successful Update Doesn’t Mean a Node Works

After an update, check that node entries appeared, the right group was updated and the protocols look as expected. A successful subscription request only means content was retrieved; nodes may still be expired, unreachable or use fields unsupported by your core. Choose one node to test. Don’t change the group, core, routing and traffic-handling mode all at once, or you’ll lose your baseline for comparison.

Open the node editor and check the server address, remote port, authentication ID, transport and security settings. Don’t casually clear fields such as the WebSocket path or host, TLS server name or REALITY public key. If fields are missing after parsing, check the source format and client support. Disabling security checks won’t make up for missing parameters.

In v2rayNG and v2flyNG, save subscriptions in a clearly named group before updating and selecting a node. Menu labels may differ on Android, but saving a subscription URL and starting a proxy connection are still separate actions. After updating, make sure the selected node wasn’t removed, and check the startup logs instead of judging by whether the list got longer.

Two Network Paths for Subscription Updates

Subscription update requests may go direct or through the current proxy. If you don’t have a working node yet, try a direct update if the source allows it. If you already have a stable node, try updating through the proxy. These options change the request path; they won’t fix an expired URL, invalid credentials or a server returning the wrong format. Check the logs before switching paths.

An empty list can have several causes: the request failed, the response was a webpage instead of subscription data, the format isn’t supported, or a filter hid all entries. If the server returned a login page, importing it again won’t create working nodes. If the issue is a group filter, restore the full list. Note the exact error to avoid pointless retries and give the source useful information.

To sync multiple devices, share the subscription source and manage device-specific system proxy settings, ports and routing separately on each one. Standard share links don’t carry every global setting. For options, see Syncing V2Ray Settings Across Devices. For the basic import flow, see the subscription steps in Quick Start.

05 / proxy modes

Proxy Modes: Traffic Handling and Outbound Selection

System Proxy Controls How Apps Connect

A system proxy registers a local HTTP or SOCKS address with the OS so apps that honor the setting can use the client. It doesn’t automatically route every network packet through the proxy. Some browsers use the system setting; other apps have their own network configuration. Command-line tools, games and background services may ignore it entirely. When testing, confirm that the app supports this inbound.

In v2rayN, actions such as setting or clearing the system proxy change the proxy state stored by the OS. After setting it, confirm the local listener is still running. After clearing it, check that the app hasn’t saved its own proxy settings. Some apps read the system proxy only at startup and need to be reopened after a change. Existing connections may keep using their old route, so refreshing a page alone isn’t a reliable test.

Linux desktop environments usually let you enter manual proxy addresses in network settings. Set the SOCKS host to the local loopback address and its port to the client’s corresponding inbound. For HTTP, use the client’s HTTP or compatible mixed inbound; don’t point every proxy type at an arbitrary port. Whether desktop settings apply to terminal processes also depends on how each program handles its environment.

Global and Bypass Rules Control Where Traffic Goes

Global proxy mode usually means that destinations reaching the core are sent mainly through a proxy outbound; it doesn’t mean every OS app is being intercepted. Preset routing such as bypassing mainland China uses domain and IP categories, along with rule order, to decide what goes direct and what goes through a proxy. These settings work at different layers, so “global is on, but this app still connects directly” doesn’t necessarily mean the core is broken.

Start with the default routing and confirm that common destinations work before changing it. Browsing and everyday work often require a mix of local and remote services; developer tools may need their own proxy settings; games can also depend on UDP, server region and latency. Choose a mode based on whether the app’s traffic enters the core and whether the selected outbound supports it—not on the mode name alone.

Android VPN routing differs from the desktop system proxy. A client may offer per-app routing or a LAN bypass, but these are separate from the core’s routing rules. If an app is excluded from VPN coverage, its traffic never reaches the core’s domain rules. Changing core routing can’t override an exclusion already made at the OS level.

Test Traffic Through a Specific Inbound

curl -x socks5h://127.0.0.1:10808 -I https://www.example.com

This command explicitly uses the SOCKS inbound, making it useful for separating proxy issues from system proxy settings. socks5h lets the proxy resolve the destination hostname; replace the example with the port your client currently uses. An HTTP response shows that this request path worked, but the status code depends on the destination site. No single status code proves the entire network is working.

If the command can’t connect to the local port, check the listening address and port. If it reaches the inbound but the handshake fails, check the node and logs. If the command works but the browser doesn’t, check the browser’s own proxy, extensions and secure DNS settings. This order helps distinguish app issues from server problems without enabling TUN as a first resort.

By the end of this chapter, you should be able to answer two questions: which inbound brings app traffic into the client, and which rules select its outbound? Routing is verifiable only when both are clear.

06 / routing

Routing Rules: Priority and DNS Boundaries

Start with a Few Specific Rules

Routing rules send requests through a chosen outbound. Common conditions include domains, destination addresses, ports and network types. Rules are usually checked from top to bottom, and the first match determines the outbound. Put exceptions for specific destinations before broad rules. If you route everything through a proxy first and add direct exceptions below, the earlier rule will often catch the requests before they reach those exceptions.

For domain rules, full: matches an exact domain, domain: matches a domain and its subdomains, and geosite: refers to a domain category. A bare string may match as a keyword, which can broaden the match unexpectedly; beginners should use explicit prefixes. CIDR in address rules specifies a network range. Category sets depend on local resource files—they aren’t live lookup services.

{
  "routing": {
    "domainStrategy": "AsIs",
    "rules": [
      {
        "type": "field",
        "domain": ["full:www.example.com"],
        "outboundTag": "proxy"
      },
      {
        "type": "field",
        "domain": ["geosite:cn"],
        "outboundTag": "direct"
      },
      {
        "type": "field",
        "ip": ["geoip:private"],
        "outboundTag": "direct"
      }
    ]
  }
}

This is a configuration snippet, not a complete runnable configuration. Before using it, confirm that the selected core has outbounds named proxy and direct, and includes the required category resources. v2rayN’s graphical routing interface generates the core configuration; map added rules to outbounds already available in the interface. Don’t overwrite client-generated files directly, as switching nodes or restarting may regenerate them.

DNS Settings: Know Who Resolves the Domain

DNS translates domain names into addresses, but resolution can happen in the app, OS, core or elsewhere in the proxy chain. Browser secure DNS, built-in resolvers and system DNS settings may all operate independently. Changing the core’s DNS server doesn’t guarantee every app will use it. If an app has already resolved a domain to an IP address, domain-based routing may no longer have the original name to match.

AsIs means the routing stage won’t proactively resolve a domain for address matching; other domain strategies may trigger resolution when needed. Core DNS settings, routing domain strategies and outbound DNS behavior are related but separate. Don’t assume an address rule miss means the DNS server failed. First check whether the request contains a domain name or an IP address, and whether the current strategy resolves it.

During troubleshooting, compare the same destination using the app’s direct connection, an explicit SOCKS inbound and the system proxy. If only the browser has issues, check its DNS resolution and cache. If the logs show DNS timeouts, check the route and reachability of DNS requests. Don’t use hard-coded destination IPs as a long-term workaround; IP changes, certificate names and CDN routing can all make it unreliable.

Verify Rules and Resolve Conflicts

Save the existing rules before editing, and make each new rule target one reproducible destination. During testing, check the destination and outbound in the access logs; a working webpage alone doesn’t show which rule matched, since both direct and proxied routes may work. If there’s no request in the logs, revisit the previous chapter’s traffic-handling settings. If the outbound is wrong, check earlier rules, category resources and the destination format before changing rule order.

Multiple conditions in one rule usually all need to match; multiple candidate values in the same field are usually alternatives. Setting both a domain and an address may make a rule stricter than expected. If you want to match either the domain or the address, use two separate rules. They’re clearer and make it easier to identify which condition failed.

07 / tun

TUN Mode: Expand Traffic Coverage and Keep a Recovery Path

When to Use a Virtual Network Adapter

TUN receives network traffic through a virtual network device. It’s useful for apps that can’t use an explicit proxy, ignore the system proxy or need broader traffic coverage. It changes how traffic enters the proxy chain; it won’t revive a broken node. If an explicit SOCKS test already fails, fix the node and core first. Enabling TUN would only extend the same failure to more apps.

What TUN actually does depends on the client implementation, core, network stack and OS permissions. Seeing an “Enable TUN mode” option doesn’t mean every requirement is met in your environment. The client may rely on companion components for the virtual adapter, routing and DNS. Check the logs to confirm what actually started instead of assuming every desktop platform works the same way.

Before enabling TUN, note the current node, system proxy state and default route, and make sure you can still reach the setting that turns it off. Take extra care on remotely managed devices: a route change could disconnect your session. Test in an environment you can access locally before using it on a device that needs a continuous connection, and keep a recovery method that doesn’t rely on the proxy network.

Permissions, Routes and Loops

Creating a virtual device and changing routes may require administrator permission. On Linux, check that the system provides a TUN device and that you have the necessary permissions. macOS and Windows may prompt for system approval or component installation. When you see a permission error, use the logs to locate the failing step. Don’t recursively change permissions across the configuration directory or run everything as administrator to hide the issue.

Traffic the proxy uses to connect to its server must be able to leave the virtual device. Otherwise, a routing loop can occur: the core’s own connection gets intercepted again and never reaches the remote server. Automatic routing and exclusion mechanisms usually handle this, but other VPNs, virtual adapters or custom routes can conflict. Before testing, disable other traffic interception tools and establish a single route through the chain.

Check LAN access separately. Printers, file shares, development servers and router admin pages may need a local route. Bypassing the LAN doesn’t mean sending every unknown address direct; it means handling local address ranges and names appropriately. If remote sites work but local services don’t, check local routing and DNS before switching nodes.

Verify in Stages—Don’t Enable Everything at Once

Keep the verified node and simple routing rules. Clear unnecessary system proxy settings, enable TUN and check the startup logs. Then test the browser, an app that normally ignores the system proxy, and LAN services one at a time. This shows whether traffic coverage has actually expanded. If you also change DNS and routing, it’s much harder to tell whether the issue came from the virtual device or the new rules.

UDP requires support throughout the chain, including how app traffic enters, how the core handles it and what the server supports. Enabling TUN doesn’t guarantee that every UDP request will work or improve gaming. Some apps also use separate authentication or voice services, or require a specific network interface. Check logs for the feature that fails rather than testing one webpage and assuming every protocol works.

After waking from sleep or switching between Wi-Fi and wired networks, check the virtual device and default route again. A network interface change can invalidate the previous state; restarting the traffic-handling service is more sensible than changing nodes at random. If this happens frequently, record the interfaces, routes and logs before and after the issue. Decide whether to keep using TUN once you have a reproducible case.

08 / maintenance

Routine Maintenance: Updates, Backups and Troubleshooting Notes

Keep Three Types of Updates Separate

The client app, subscription content and routing category resources are three separate things. A client update changes the interface or implementation; a subscription update changes the node list; a resource update affects domain or address rules. Don’t update all three while troubleshooting one issue. After each type of update, test against your existing baseline before moving on.

Before updating the client, read the release notes for features you use and check that your core and configuration format are still supported. You don’t need to reinstall just to chase version numbers, but don’t ignore updates with compatibility or security fixes. After upgrading, check node startup, subscription parsing, routing and traffic handling—not just whether the app window opens.

Set subscription update frequency according to how often the source changes. Frequent requests won’t fix invalid credentials and may trigger server limits. If a node disappears after an update, first check whether it was intentionally replaced, then select another entry. If a routing category update changes a destination’s outbound, inspect the matched category and exception rules instead of sending everything through global proxy mode.

Make Sure Your Backup Can Be Restored

Back up at least your subscription groups, manual nodes, routing rules and important global settings. Prefer the client’s built-in export. Quit the program before copying its configuration directory to avoid copying files while they’re being written. Storage paths and formats vary by platform; verify where your current client actually stores its data instead of inferring the path from another OS.

Configuration backups may contain server authentication details, subscription credentials and device-specific settings. Store them somewhere access-controlled. Make a separate redacted copy of screenshots or logs for troubleshooting; never post the original backup publicly. When migrating, import on the new device and check the listening address, ports, permissions and traffic-handling method. Don’t blindly copy environment-specific settings from the old device.

Test that your backup can actually be restored. Export the configuration, note a few key settings, then import it into a separate test environment and verify them. A file’s existence alone doesn’t prove the backup is usable. For cross-platform restores, check for incompatible paths, startup entries and permission settings. Node data may carry over, but OS integration often needs to be set up again.

Troubleshoot in Order Along the Connection Path

For connection problems, check the system clock and basic network first, then the local inbound, core logs, node connection, DNS and routing. A clock that’s significantly off can affect handshakes or authentication. If the underlying network is down, restore it first. If the local port isn’t listening, fix core startup rather than guessing about the remote server or routing categories.

When documenting an issue, include the time, client, core, traffic-handling method, failed destination and exact error. “It doesn’t open” doesn’t distinguish a connection timeout from a DNS failure, certificate error or app-specific message. Share only the relevant log lines before and after the issue, preserving their order while hiding sensitive fields. Raise the log level only for short-term diagnosis, then restore the usual level.

As part of routine maintenance, review leftover settings: unused subscriptions, duplicate nodes, temporary rules and old startup entries should all have a clear purpose. Back up before deleting, then test again after cleanup. Avoid piling on configurations from unknown sources; it makes future problems harder to trace and can leave old clients restoring system proxy settings in the background.

09 / next steps

Advanced Topics: From a Working Setup to an Understandable One

Inspect Generated Configuration Before Customizing

Advanced setup isn’t about adding more toggles; it starts with being able to explain the configuration you already have. Find the client’s configuration viewer or logs and identify how inbounds, outbounds, routing and DNS fit together. A single graphical setting may generate several core fields. Understanding that mapping explains why interface changes affect behavior and helps you avoid treating a temporary generated file as a permanent source of configuration.

Before using a custom configuration, find out how the client loads it and which graphical settings still apply. A custom file may bypass parts of the interface’s configuration generation, so the routing mode shown in the UI may not reflect the actual rules in the file. With a complete custom configuration, rely on the final loaded file and runtime logs rather than assumptions based on graphical options.

Checking JSON syntax is only the first step. Correct brackets, commas and strings don’t mean the core supports every field or that outbound tags match. Check the structure first, core compatibility second and network behavior last. Define a specific test target for every feature you add. A clean startup doesn’t prove that every route works.

Design Experiments Around a Specific Task

To route a development tool through the proxy, first check its own proxy support, then choose the system proxy, an explicit inbound or TUN. To send a domain direct, confirm the request still contains the domain and add a dedicated exception. To investigate DNS differences, compare how the app and core resolve names. Narrowing the problem to one task is usually more reliable than importing a large, unknown configuration.

Before testing, write down what you expect: which app, destination, inbound and outbound. Afterward, use the logs to confirm what happened. If the test fails, restore the last working configuration. This gives you a record to repeat after an upgrade or migration, and separates configuration intent from actual behavior. Don’t use a single result from a test site to infer how traffic from every app on the device is routed.

Performance comparisons also require controlled conditions. Keep the device, network, destination and test window as consistent as possible, and compare connection setup, sustained transfer and long-term stability. One download speed doesn’t describe a node’s overall performance; server limits and destination congestion also matter. Don’t invent latency figures or rank protocols by name—record repeatable observations instead.

Protocol Concepts and Security Boundaries

Before exploring VLESS, REALITY and XTLS Vision, learn the basics of TLS handshakes, authentication and transport layers. REALITY uses handshake parameters agreed between the client and server; Vision handles specific flow-control behavior. Neither is a standalone speed boost. Check all fields provided by the node source together. If required parameters are missing, confirm the configuration requirements instead of guessing from a tutorial.

Read How REALITY and XTLS Vision Work for the technical background, then check whether your chosen core supports them. The explainer covers the mechanisms; an actual connection still depends on the server configuration. You don’t need to change a working setup while learning—keep a separate test entry so everyday use remains unaffected.

A proxy doesn’t replace an app’s own security measures. Website identity, account authorization, file sources and device permissions still need separate attention. Before allowing LAN connections, exposing a local inbound or importing an unfamiliar custom configuration, understand who can access it and what it does. When sharing tips, show only the structure and redacted details needed; never include credentials that provide direct access to personal services.

Keep a simple, working configuration as your baseline, then add only the features you need. A maintainable setup gives every setting a purpose, a way to verify it and a way to undo it. You don’t need to enable every advanced feature at once.