V2Ray Setup Guide for All Platforms

For your first connection, start with the quick-start guide. This manual covers installation, importing configurations, and traffic routing by platform. Use the relevant section when switching devices or network modes, or when troubleshooting.

Before you begin

Choose the right OS, architecture, and package

For desktop, start with v2rayN. On Android, v2rayNG with the Xray core is the recommended choice; use v2flyNG only when you specifically need the v2fly core. First identify the operating system currently running on the device, then check its architecture. The model, purchase year, processor brand, and system architecture are not interchangeable: devices from the same brand can use different architectures, and a virtual machine may run a different OS from its host. For a virtual machine, check the system information inside the VM rather than choosing a package based on the host.

Go to the relevant platform section on the download page and choose a package based on the type listed on its card. Follow the system requirements on that page: a matching architecture only means you have the right build target; it does not guarantee that your OS, runtime, and desktop environment meet all requirements. For a first install, keep the default local listening settings, leave LAN access disabled, and avoid enabling startup traffic interception. That makes it easier to tell a client startup problem from a network routing problem if the initial import fails.

PlatformClientHow to choose a packageTraffic routing method
Windowsv2rayNx64 desktop or WPF buildSystem proxy; enable TUN if needed
macOSv2rayNApple Silicon or IntelProxy settings for the network service; enable TUN if needed
Linuxv2rayNDistribution package format and processor architectureDesktop or application proxy; enable TUN if needed
Androidv2rayNG、v2flyNGarm64 or universal buildThe client routes traffic through the system VPN interface

Tell subscription URLs, nodes, and local configurations apart

A subscription URL retrieves a set of nodes and belongs in the subscription manager. A single share link or QR code describes one node and should be imported through the single-node flow, such as clipboard import or scanning. Mixing them up can cause repeated format errors during subscription updates, or a URL may appear to save successfully without adding anything to the list. First identify what kind of content the provider supplied, then check that it can be parsed by your chosen client. A complete configuration file for another application is not a regular subscription.

A subscription URL may contain access credentials, so treat it like a password. Don't paste it into online converters, public screenshots, or forum posts. Subscription conversion changes how node details are represented; it cannot make a target core support protocols or transport settings it doesn't otherwise support. If the format is incompatible, ask the configuration provider for a subscription suited to your client before considering a migration. When exporting a backup, check whether it includes subscription URLs, local nodes, or access credentials. Use protected local storage where possible, and don't share sensitive exports publicly.

Record the setup before and after connecting

Before connecting, confirm the device can access the internet, and check that its date, time, and time zone are correct. If the current network requires a web sign-in, complete that first. Then note any existing system proxy, automatic proxy script, work VPN, and per-app proxy settings. The goal is not to clear existing settings, but to restore them after testing. Keep management policies intact on managed devices. If you aren't sure who owns a setting, don't overwrite it.

Choose an authorized HTTPS URL you can open repeatedly as a test target, plus a LAN service that normally needs a direct connection for comparison. For the first test, use one node, one app, and one traffic routing method. Client logs can confirm local inbound traffic and the selected outbound; the app's actual response shows whether the service works. A node appearing in the list, the core starting successfully, and the target responding are three different outcomes. When something fails, note which step failed instead of simply reporting that the proxy doesn't work.

Keep a working device as a reference when possible. After importing the same subscription on a new device, confirm that the node group and test target match, then compare the traffic routing methods. If neither device can update the subscription, check whether the subscription service is reachable. If only the new device fails, start with system permissions, app settings, and the local network. Don't overwrite a working device first; that makes it harder to pinpoint the failing step.

Windows: Install and route traffic with v2rayN

Choose the desktop or WPF build

Open Settings → System → About and check the system type to confirm it is x64-based, then visit the Windows downloads. The desktop build uses a cross-platform interface; the WPF build has the classic Windows interface. Menus may differ between the two, so if you can't find a button shown in a screenshot, look for the subscription manager, node selection, or system proxy controls. Run only one client at a time: multiple instances can compete for local ports and overwrite each other's proxy settings.

Launch the installer for the package type shown on the download page, or fully extract the archive and run the client from its extracted folder. Don't drag out and run only the main executable; it still needs to find its core and related resources. Start it under your everyday account the first time rather than running it as administrator by default. If it exits before the main window appears, check the system message and the runtime requirements listed on the download page. If the window opens but the core fails to start, check the logs for missing resources, access denied, or a port already in use.

Update the subscription and test one app

Open subscription group management, add a clearly named group, enter the subscription URL, and save it. Switch to the new group and run the update command, then confirm the new entries belong to that group. Saving without an error only confirms that the settings were written locally; a successful update means the client retrieved and parsed the content. Select a node and set it as active, then check the logs for startup errors. If an older group is still listed, don't mistake its entries for the results of this update.

Select Set system proxy from the tray menu, then use a browser configured to follow the system proxy to open your test target. Open Windows Settings → Network & Internet → Proxy to check whether the settings actually changed, and compare them with the local proxy address and port shown in the client. Enabling the system proxy doesn't route every app the same way: terminals, services, some download managers, and browsers with their own proxy settings may use separate connection paths. If the browser works but another app doesn't, check that app's proxy settings before assuming the node is unavailable.

Clear conflicting routes before trying TUN

Try v2rayN TUN mode only if a target app ignores the system proxy or you need to route traffic through a virtual network interface. First exit other proxy tools that modify the default route, restore the system proxy state from before the test, and enable only one new mode at a time. Grant the permissions the client requests to create a virtual network adapter. Check the logs alongside the app's results: a button showing that TUN is on doesn't guarantee the route was applied, especially after waking from sleep, switching between Wi-Fi and Ethernet, or when other virtual interfaces are active.

If the internet works but a printer, file share, or intranet service becomes unreachable, turn TUN off first and see whether access returns. If it does, check the LAN subnet, domain names, and rule priority rather than immediately routing more traffic. If connectivity is still broken after TUN is off, check the system proxy page for a leftover local port or script. Restore settings based on your pre-test notes; don't simply turn everything off on a device that was already using a work proxy.

Find port conflicts by checking listening sockets

If the logs report an address-in-use error, use PowerShell to check local listening sockets. The command below lists connections in the listening state. Compare the local port in the output with the port actually shown in v2rayN settings instead of guessing from the default. The process ID can help identify what's using the port, but doesn't prove that process is misbehaving. The same program may listen on more than one address.

Get-NetTCPConnection -State Listen |
  Select-Object LocalAddress, LocalPort, OwningProcess |
  Sort-Object LocalPort

If the port is held by an old instance that is still running, exit it normally from its tray menu. If the port belongs to an app you need, choose an unused local port and update any apps where you configured the proxy manually. Restart the connection, check that the listening socket appears, and test again in one app. If the port is listening but access still fails, investigate traffic routing and outbound logs instead of repeatedly changing ports.

macOS: Install v2rayN and configure network services

Choose the disk image for your processor

Open About This Mac from the Apple menu. If it shows an Apple chip, choose the Apple Silicon build on the macOS downloads page; if it shows an Intel processor, choose the Intel build. A terminal's behavior doesn't tell you the architecture of the whole device, since the terminal process may be running in a compatibility environment. Open the matching disk image and follow its instructions to copy the client to Applications. Launch the copied app rather than running it from the mounted image, then eject the image once you've confirmed the app opens.

If macOS blocks the app, first identify whether the alert is about a security policy, an unsupported system version, or an app that exits unexpectedly after launch. Follow system prompts only for an app whose source you can verify and that complies with your device's management requirements. If your organization's policy blocks it, contact your administrator rather than disabling system protections. Check the app logs only after its window opens. If the failure occurs during loading, changing subscriptions, proxy settings, or DNS won't fix a binary compatibility issue.

Check the system proxy on the active network service

Add a group in subscription management, update it, and select a node. After enabling the client's system proxy, go to System Settings → Network, select the service for your current connection, and check its proxy settings. Wi-Fi and Ethernet are separate network services, and old settings may remain on each. After attaching a network adapter, unplugging a dock, or switching from a company network to a home network, proxy settings on an old service don't confirm that the active service uses the same route. Compare the active service with logs from the current session.

You can also run the read-only command below in Terminal to view the proxy configuration currently reported by the system and the order of network services. The output can show whether a proxy is enabled, whether its port points to localhost, and sometimes whether automatic configuration is set up. It doesn't prove that every app uses those settings. Check the actual request path separately for apps with their own proxy settings or terminals that rely only on environment variables.

scutil --proxy
networksetup -listnetworkserviceorder

If the client logs don't show inbound requests from the app you expect, fully quit and reopen that app. Some programs read proxy settings only at startup, so a process that's been running may still use its previous settings. To check that the proxy has stopped, don't just switch windows: turn off the client's system proxy and, if needed, quit the app, then confirm the active network service has returned to its original state. Keep organization-managed automatic proxy addresses in place; don't remove them just for comparison.

Verify TUN after sleep and wake

If the system proxy works for your target app, there's no need to enable TUN just to make the interface show a particular state. To route an app that ignores proxy settings, turn off the system proxy for this test and enable the virtual network interface as prompted by v2rayN. Test domain access first, then LAN services, and finally both again after a normal client shutdown. Testing only an external website can miss LAN issues caused by the virtual interface changing the default route.

If the connection works before sleep but fails after waking, first check whether Wi-Fi has reconnected and whether the client logs still show incoming requests. If Wi-Fi hasn't recovered, fix the network connection and address assignment first. If Wi-Fi is back but the app has no inbound traffic, check whether the system proxy or virtual route is still active. Restart the relevant mode only after confirming the old session is stale, then see whether the problem recurs reliably. This helps distinguish wake-from-sleep issues from a node change in the subscription.

Separate device discovery, DNS resolution, and app connectivity

Troubleshoot LAN access in layers. First test the service using a device address you know is reachable, then try accessing it by its device name. If the address works but the name doesn't, focus on name resolution or local service discovery rather than changing the remote node. If even the known device address fails, compare the network interfaces and rules before and after enabling traffic routing. Remote DNS servers usually can't resolve device names on your local network, so successful external HTTPS access doesn't prove that LAN name resolution works.

If the problem occurs only with one dock or one network, record the active service name, routing mode, and type of test target. Turn off recent changes, restore the last known-good settings, and repeat the test one step at a time. Don't delete every network service and client setting at once: even if the problem disappears, you won't know whether the proxy recovered or the system switched to a working network.

Linux: Install v2rayN and configure desktop proxy settings

Package format and architecture

First check the distribution's package management system, then the machine's architecture. Debian, Ubuntu, and desktop distributions that use their package system generally use deb packages; Fedora and related distributions use rpm. The fact that an installer can read another format doesn't make deb and rpm interchangeable. The main Linux downloads are for x64, with arm64 also available. If your distribution isn't listed as supported, matching package formats alone don't guarantee compatibility.

uname -m
cat /etc/os-release

uname -m usually returns x86_64 for an x64 build and aarch64 for an arm64 build. In a container or special compatibility environment, the kernel-reported architecture may differ from the userspace package architecture; confirm it with the target system's package manager. Check distribution information to choose the right local package format. You don't need to edit any fields or change software sources just to install the client.

You can start with the desktop's built-in package installer. From the command line, run the command for your distribution in the directory containing the package. The examples assume you've renamed the downloaded package to v2rayn.deb or v2rayn.rpm; run only one command. The package manager will try to resolve dependencies. If it reports unmet dependencies, check the system version and configured repositories rather than forcing installation while ignoring them.

# Debian / Ubuntu
sudo apt install ./v2rayn.deb

# Fedora
sudo dnf install ./v2rayn.rpm

Import the subscription as your desktop user

Installation may require elevated privileges; that doesn't mean the client should run with elevated privileges every day. Launch it from your current desktop session, then add a subscription group, update it, and select a node. If you previously launched it with elevated privileges, it may have read or written a different configuration, so the list may look different under your regular account. If the configuration directory has a permissions error, check its exact location and ownership instead of recursively loosening permissions across your home directory. When the core fails to load, preserve the first error rather than only capturing repeated retry messages.

Desktop proxy behavior depends on the current session. After the client updates desktop settings, only apps that read those settings will use the proxy. Apps in another desktop environment, sandboxed apps, programs launched by another user, and terminals that were already open may not have the same proxy configuration. First test a regular desktop browser, then test the target app separately. If only the target app fails, consider configuring its own proxy instead of assuming the desktop proxy is broken.

Test the local proxy explicitly

If desktop apps and terminal tools behave differently, explicitly route a terminal request through the client's HTTP or mixed proxy port. The commands below read input and don't make persistent changes to system or shell settings. Enter the local port shown in the client, not the node's remote port, and use a test URL you're authorized to access. The HTTP example won't work if only a SOCKS inbound is enabled. The test URL must respond to a HEAD request; otherwise, use a regular GET request.

printf 'Local HTTP or mixed proxy port: '
IFS= read -r proxy_port
printf 'HTTPS test URL: '
IFS= read -r test_url
curl --noproxy '' --proxy "http://127.0.0.1:$proxy_port" \
  --head --max-time 15 -- "$test_url"

If the connection to localhost is refused, check that a process is listening and that the port type matches. After receiving an HTTP response, use the client logs to determine whether the request was proxied, sent direct, or rejected; the status code alone doesn't show which outbound handled it. If the explicit test works but your usual terminal tools still fail, check their own network settings. Don't assume that one test with explicit proxy parameters means every command now inherits the proxy.

Virtual interfaces, default routes, and rollback

Before testing TUN, confirm that the kernel supports virtual network interfaces, your desktop session has the permissions the client needs, and you've recorded the default route and LAN reachability in the normal state. Containers, remote desktops, and managed systems may not be able to create the required interface. Don't run the entire graphical session with elevated privileges to work around interface creation problems. If another work network becomes unreachable after enabling TUN, first disable the new routing mode and compare routes. Don't flush the route table in a remote session.

The network manager may reapply device settings after reconnecting, so test both initial activation and one normal reconnect. If it fails only after reconnecting, note the interface, network, and time of the error; first check whether the default route was lost, then investigate the client state. After a normal shutdown, check desktop proxy settings, per-app proxy settings, and the virtual interface separately. Reverting one doesn't automatically revert the others.

Android: v2rayNG and v2flyNG

Choose a client and package architecture

The Android downloads list v2rayNG first, followed by v2flyNG. v2rayNG uses the Xray core and is the recommended first choice; use v2flyNG when the subscription specifically requires the v2fly core. The apps have similar workflows, but don't assume they support the same protocols, transport combinations, or import details. Choose arm64 if the device system supports arm64 apps; if you're unsure, check the device specifications or choose the universal build. A 64-bit processor doesn't guarantee that the manufacturer installed a system supporting the same app architecture.

Open the package from your file manager. If Android asks you to allow app installs from the current source, grant the necessary permission only to the app opening the file, then revoke it in Settings if you no longer need it. If an update won't install, distinguish between an architecture mismatch, an unsupported system version, device management restrictions, and incompatibility with the existing app. Don't uninstall an app you're using without a reason: local nodes, per-app lists, and preferences may not be preserved. Back up first if you're sure you need to migrate.

Update the subscription and grant VPN permission

Open subscription group settings and add the URL with a recognizable name. Return to the node list, update the subscription, select one of the newly retrieved nodes, and start the connection. Clipboard import is for a single share link; don't send the same subscription URL through clipboard import just because an update failed. If the logs show that retrieval failed, first check whether the current network can reach the subscription service. If content was retrieved but no usable entries appear, check the subscription format and core compatibility.

The system usually asks for VPN permission the first time you connect. Confirm that the selected client is requesting the connection, then grant permission. The client uses the system's virtual network interface; another work VPN, local firewall, or filter using that interface may conflict with it. If Always-on VPN was previously configured, check which app it applies to. Don't copy the desktop instruction to set a system proxy as a mobile step, and don't run two clients at once to compare nodes.

Per-app routing and network changes

For your first test, use the default traffic routing scope to check a browser. Don't add per-app rules yet. Once that works, enable per-app proxying and confirm whether the setting means “route only selected apps” or “exclude selected apps.” Retest with one app that should be routed and one that shouldn't. If the browser works but an in-app page doesn't, check whether the request comes from the main app, a system component, or an external browser. Choosing apps based on their icons can lead to the wrong list.

If Wi-Fi works but mobile data doesn't, first check whether a regular webpage opens on mobile data with the client off. Then see whether the connection is re-established after switching networks. Mobile data permissions, data-saving settings, and network access requirements can all affect the result. The VPN icon only shows that the interface is still present; it doesn't mean the existing remote connection carried over to the new network. Note the first error before and after switching networks; repeatedly tapping reconnect is less useful for diagnosis.

Background restrictions and always-on settings

If the connection stops when the screen locks and returns when it wakes, check system battery and background activity settings first. If you can reproduce the issue, adjust battery restrictions for this client only and retest with the same network and lock-screen duration. There's no need to remove restrictions for every app. Always-on VPN controls the connection policy; blocking connections that don't use the VPN is a separate restriction. That can also block normal internet access when the client stops, and may affect apps that need a direct connection. Check device policies and your needs before enabling it rather than using it to hide a background shutdown.

When troubleshooting battery drain, distinguish continuous traffic forwarding by the client from frequent app requests and repeated reconnects caused by an unstable network. Compare battery usage over the same time period, keeping the network and app scope consistent during testing. For details on battery optimization, manufacturer background controls, and per-app settings, see Troubleshoot v2rayNG battery drain and background activity.

Reconfigure system settings after changing devices

Reimporting a subscription restores the node list, but it doesn't configure the new device's VPN permission, data usage permissions, or per-app list. After switching devices, establish a basic connection first, then add background and always-on settings, and finally compare app access on both devices. To move only a few self-hosted nodes, share individual links as needed. If you also need to preserve routing and preferences, check which settings can be included in a configuration backup. See Sync V2Ray settings across devices.

Routing and DNS

Traffic interception, rule matching, and outbounds

First distinguish “did the app send its request to the client?” from “where did the client send it?” System proxy or TUN handles the first; routing rules handle the second. If the request never reaches the client, changing rules won't affect it. If the logs show that the request was received but sent through the wrong outbound, check rule order, match conditions, and the default behavior. There's no need to enable another traffic routing mode.

Standard routing rules are evaluated in order, and the first matching rule usually determines the outbound. Put specific domain rules before broader rules that might match first. A rule's outboundTag must reference an outbound tag that exists in the configuration; it isn't an arbitrary label. direct, proxy, and block are common example names, but not every configuration uses them. If no rule matches, the core usually uses the first outbound, though graphical clients may add fallback rules. Check the actual configuration and logs instead of inferring behavior from a mode name in the UI.

Check the specific rule before changing the default route

This Xray-compatible domain rule matches the exact domain example.org and sends it to the existing direct outbound. It's one object in the routing.rules array, not a complete configuration. To verify rule order, make sure the outbound exists, place the rule before a broad match in a test configuration, and compare outbound logs for this domain and another test target. If a graphical client has a routing editor, enter the relevant fields there rather than pasting the whole object into a field that accepts only domains.

{
  "type": "field",
  "domain": ["full:example.org"],
  "outboundTag": "direct"
}

A domain rule can match only a domain the core can see. It may not apply when you access a literal IP address, an app resolves the name itself before connecting, or a virtual interface sees only the destination IP. Some configurations can use traffic sniffing to infer a domain, but whether that works depends on the traffic and settings. For a LAN device that needs a direct connection, first determine whether the app uses a local name or a specific address, then choose a domain condition or a narrowly scoped IP condition. Avoid excluding unrelated address ranges.

Which component resolves the domain?

V2Ray DNS settings can involve several layers: the OS may resolve a name first, a browser may use its own secure DNS, and the core may perform lookups for routing decisions or outbound connections. Enabling remote DNS doesn't send every query through it, and TUN doesn't automatically control every app's built-in resolver. When troubleshooting, identify which kind of query you need to test, then compare logs, app settings, and system resolution. External domains and names used only on a LAN usually need different resolution paths; sending both to the same resolver can make issues harder to diagnose.

If a site is available only by domain, don't use direct IP access as proof that HTTPS works. Its certificate, virtual host, and handshake may depend on the server name. Instead, record whether DNS resolution succeeds, whether the app establishes a connection, and which outbound the core selects. To avoid stale app results, quit and reopen the app you're testing. Don't treat a cached result immediately after changing settings as proof that the new settings took effect. For a systematic check of DNS query paths, see DNS leak testing and configuration.

When to use domain strategies and FakeDNS

The core's domain strategy affects whether it resolves a domain to an IP address for IP-based routing rules. In Xray, for example, AsIs doesn't actively resolve domains to IPs for routing matches. IPIfNonMatch tries resolving a domain for IP rule matching only if no domain rule matches. Resolving a domain for routing and choosing the address for the final connection are separate settings. Changing the strategy can affect when resolution happens and which rule matches, so retest both destinations that should go direct and those that should use the proxy.

FakeDNS maps synthetic addresses back to domains, which the core then restores for intercepted traffic. The DNS response and subsequent connection need to follow compatible routing paths. If a device receives a synthetic address but connects through a path the core doesn't intercept, resolution may succeed while the connection fails. For a first setup, get regular DNS and routing working first. Use FakeDNS only when you specifically need domain mapping; read How FakeDNS works and when to use it, then test it separately. When rolling back, remove the related mapping settings and reconnect the test app.

Common setup questions

Subscription saved, but why is the node list still empty?

Check whether retrieval or parsing failed

First make sure the active group is the one you updated. If the update log reports a domain resolution failure, connection timeout, or unexpected server status, the problem is still in the retrieval stage. Retry on an existing, authorized network that can reach the subscription service; a subscription can't provide a connection through a node that hasn't been imported yet. If retrieval succeeds but the format isn't supported, ask the provider whether the response is a subscription your client can parse rather than a login page, error message, or complete configuration for another app. Don't share the response or original URL; record only the error type and time.

If the list used to work but some entries disappeared this time, check whether you switched groups, then confirm whether the server replaced nodes or removed entries. A subscription update may overwrite nodes already in that group. Keep manually maintained configurations in a separate group so you can tell subscription changes from local edits.

A node passes its test, so why can't the app connect?

Understand what the test actually measures

A V2Ray node test may check only the transport connection to the server, or it may access a test URL configured in the client through the node. A successful test proves only that specific check worked; it doesn't guarantee access to another domain or app, or that a different DNS setup works. First confirm the tested node is the active one, then make a new request in the target app, note the time, and check the core logs. If there's no inbound request, check the system proxy, virtual interface, or app scope. If there is an inbound request and the expected outbound is selected, investigate the remote connection and the target service response.

Results from different test URLs, networks, and test types aren't directly comparable. A single timeout doesn't mean the entire subscription is broken. On the same network, repeat the test with one chosen URL, note whether it fails at the same stage, and compare the result with a known-working node.

Can't access any websites after enabling TUN?

Restore a working setup, then retest TUN by itself

First turn off TUN and restore the previous direct connection or system proxy, then confirm basic connectivity. If you still can't get online, check whether the current network requires a sign-in, whether a local proxy port remains configured after the client exits, and whether an always-on VPN policy is still active. Preserve any existing work network settings during recovery. If disabling TUN restores access immediately, check permissions for the virtual interface, routing conflicts with other network tools, and whether the resolver address has become unreachable.

For a fresh test, enable only TUN and keep the node and test URL unchanged. Check domain access and a local address that should normally be direct, then review the logs. “Enabled” only confirms that the client accepted the action; verify the route, interface, DNS resolution, and outbound separately.

The same subscription behaves differently on two devices. What should you compare first?

Match the client, core, and test conditions

First compare the selected node, core type, network, destination, and test time. A phone routes traffic through the system VPN interface, while a desktop may only set the system proxy. Even with the same working node, the apps being routed can differ between devices. If a node imports successfully but reports a parameter error when connecting, check whether the current core supports its protocol and transport settings. Before switching clients, use the client comparison to understand the differences, then change one variable at a time on one device.

If you need to migrate routing rules while both apps still work, don't copy every system-specific setting wholesale. The same routing behavior can be configured on both devices, but local addresses, proxy ports, app lists, and permissions need to be checked again. Instead of trying to make every option identical, verify that the traffic that should go direct and the traffic that should be routed behave as expected on each device.

Which settings should I change for a certificate or handshake error?

Keep certificate verification enabled and locate the failure

Confirm that the system date and time are correct. Identify whether the error comes from the browser connecting to the target site or from the handshake between the client and the node. If the client logs show the error, check that the imported node address, transport settings, and server name match the provider's instructions. If the browser shows it, check the test URL, whether the network requires a web sign-in, and whether the app is using a proxy left over in the system. Disabling certificate verification isn't a fix; it can hide a mismatch in the connection target or configuration.

When reporting an issue, include only the operating system, client name, connection mode, reproduction steps, and the first error with sensitive details removed. Don't attach a full subscription, node share link, or configuration export containing credentials. If you still can't identify where it fails, repeat the minimal flow in the quick-start guide, then add settings using the relevant section of this manual.