V2Ray Setup Guide for All Platforms
Install packages, import subscriptions, configure system proxy and TUN
Setting things up for the first time and just need one connection working? Follow the import, connect and verify steps in the Quick Start. This page is a platform-by-platform reference: jump to the relevant section for package selection, system permissions or routing differences. If the client is already installed but the connection is failing, start with verification and rollback.
Before you begin
Clients, cores and installation packages
For desktop, v2rayN is the go-to choice. It manages subscription groups, servers, routing rules and local traffic entry points; the active core handles the actual connections. On Android, v2rayNG with its Xray core is the usual choice. Use v2flyNG when you specifically need a V2Fly core. Check the full connection settings for compatibility: two VLESS configurations can use different transports, security settings and flow controls, so the protocol name alone won't tell you whether clients are interchangeable. If you know a subscription includes REALITY, check first that the Xray client can recognize those nodes correctly.
| Platform | Client | How to choose a package | Common traffic entry points |
|---|---|---|---|
| Windows | v2rayN | x64 desktop or classic WPF edition | System proxy, TUN |
| macOS | v2rayN | Choose arm64 for Apple Silicon or x64 for Intel | System proxy, TUN |
| Linux | v2rayN | Choose deb or rpm for your distribution, then select the architecture | Desktop proxy, explicit proxy, TUN |
| Android | v2rayNG、v2flyNG | Choose arm64 if your device supports 64-bit ARM apps; otherwise check the universal build | System VPN interface |
Go to the relevant platform on the client downloads page. Check your system's architecture first, then choose the package type. On Linux, also confirm which package format your distribution supports. Two ARM-powered devices don't necessarily use the same package; desktop and mobile apps use different formats, and systems on the same platform may support different runtime environments. If installation fails, keep the original system error and work out whether the issue is an architecture mismatch, a missing runtime component or insufficient installation permissions before changing packages or fixing the environment.
Subscription URLs, single-node links and service details
A subscription URL periodically fetches a group of servers; a single-node link imports just one server entry. A subscription management webpage is also different from the URL a client uses to fetch subscriptions. Check which one you need before copying anything, and don't paste a login page into a subscription group. Subscription URLs may contain access credentials, so don't include the full URL in screenshots, logs or support requests. If your provider gives you a QR code, check whether it represents a single node or a subscription before choosing scan or subscription import.
If you already manage nodes manually, keep them separate from nodes imported through subscriptions. Refreshing a subscription may rebuild its group, and changes made directly to subscription nodes may not stick. Give each group a descriptive label, but don't include account details, passwords or full addresses. After updating, note which group and protocol the active node belongs to so similar names don't get mixed up. If you use one subscription on multiple devices, check your provider's device limit and concurrent connection policy.
Record the starting state and keep the first test simple
Check that your device has the correct date, time and time zone, and that the test page loads without a proxy. Note your current system proxy, corporate network settings, other VPNs and the client's local listening port. If your device is managed by an organization, confirm which settings you're allowed to change. For the first setup, use one node and one traffic entry point; don't bring over old routing rules, custom DNS or other forwarding settings all at once. Once you can repeat the baseline test, add settings one at a time.
Choose two targets you can revisit: one to check a direct connection and another that should use the proxy. Keep the network, node and targets unchanged during the first test; don't switch Wi-Fi and nodes at the same time. If you're migrating from an existing client, keep its launch method and configuration directory, then test the new installation separately. Don't run two clients at once from the same writable directory. That way, you can restore the previous network state if a later change causes problems.
Windows: install v2rayN and configure the system proxy
Desktop and classic WPF editions
Open the Windows downloads. The v2rayN desktop edition uses a cross-platform interface; the classic WPF edition uses the traditional Windows interface. Menus may differ, but the basic setup is the same: add a subscription group, update it, select a server and choose how traffic enters the client. Before switching editions, exit the running instance and check the notification area for background processes. Two instances may compete for the same listening port or overwrite each other's system proxy settings when they exit.
Open Settings → System → About and check System type. An x64 package refers to the app's architecture; seeing “64-bit” in the system information alone doesn't confirm that your device uses x64. If it shows an ARM processor, check system compatibility separately. If a runtime component is required at startup, verify its name and architecture against the prompt. If the main window opens but the core fails to start, check the client logs. Don't mistake an app startup problem for an expired subscription, and don't change the package and node at the same time.
Import a subscription and select an active server
Open the Subscription Group menu. In Subscription Group Settings, add a group or use the Add Subscription Group option, then enter a label and subscription URL. Save it and run the equivalent of Update All Subscriptions. If the menu offers updates with or without a proxy, first check whether your current network can fetch the subscription directly—especially if you haven't established a working connection yet. If your provider requires a particular download method, follow its instructions. Don't use a management page or error page as the subscription content.
Wait for the nodes to appear in their group, then explicitly set one server as active. A highlighted row may only be selected; check the status bar or tray message to confirm which server is active. If an update leaves the list empty, check the group URL, update logs and subscription validity. If only a few nodes are missing, check their format and whether the current core supports them. You don't need to run a speed test on the whole group to verify installation; testing one known-good node makes problems easier to isolate.
System proxy, TUN and the right way to exit
From the tray's System Proxy menu, select Set system proxy and test with a browser that follows the system proxy. If needed, open Windows Settings → Network & Internet → Proxy and check that the proxy address and port point to the current client. Set system proxy is the client's action to configure Windows proxy settings; it isn't the same as Windows Automatically detect settings. Some command-line tools, background services and apps with their own proxy settings won't use the system proxy. A working browser doesn't mean every app is covered.
If a target app doesn't use the system proxy, check whether it has its own proxy setting. If traffic needs to go through a virtual network adapter, try enabling TUN mode. Before testing, clear the system proxy set by the client so you're testing one entry point at a time. Grant the permissions requested, then check the virtual interface, routes and local network. Don't run every tool as an administrator indefinitely just to install or troubleshoot, and don't leave another app managing the default route. Before exiting, clear the proxy and TUN settings changed during this test, then restore the configuration you recorded earlier.
macOS: choose the right package and check network services
Choose a package for your processor and understand system prompts
Open About This Mac from the Apple menu. If it shows a Chip entry for Apple Silicon, choose the arm64 installer from the macOS downloads. If it shows an Intel processor, choose x64. Open the disk image, follow the prompt to move the app to Applications, then launch it from there rather than running it from the mounted image. When updating, quit the old menu bar instance before replacing the app to avoid two copies sharing configuration or changing system settings at the same time.
If macOS blocks the app on first launch, read the message carefully. An architecture mismatch, a damaged-app warning, an unverified developer and an organization policy restriction are different issues. Recheck the installer and system architecture. If a security prompt remains, follow Apple's per-app process and your organization's requirements; don't disable system-wide security protections. If the interface starts but networking doesn't work, check the client logs. That's different from the app failing to open, and moving it to another folder alone won't fix it.
Subscription groups and menu bar status
In v2rayN, add a subscription URL and a recognizable label under Subscription Group, then update it. Open the group and check that the nodes have actual address, port and protocol fields before setting one server as active. If the update fails, check whether a regular webpage loads in your browser and whether the current network requires sign-in. Then confirm that the subscription response is content the client can parse. Being signed in to your provider's website doesn't mean the client shares that login session. If the response is a login page, copy the dedicated subscription URL from your provider's account page.
Closing the window doesn't always quit the process. Check the app's menu bar or status area to confirm the active node, proxy mode and running state. For the first test, keep the node unchanged and use the same browser window and target. If your saved configuration includes routing or custom DNS, record those settings and temporarily use simple rules for a baseline test. Before switching nodes, confirm whether the current server is actually active; a highlighted row in the list doesn't prove a connection is working.
Network services, TUN and waking from sleep
After enabling Set system proxy in the client, open System Settings → Network, select the active network service and check Details → Proxies. Wi-Fi and Ethernet may be separate network services, so a working proxy on one doesn't mean it'll remain active on the other. If you already use an automatic proxy configuration or a managed proxy, record its settings first; don't overwrite them without authorization. If a browser works but a terminal tool doesn't, check the tool's own proxy settings: not every command-line process reads the system proxy.
To test an app that doesn't use the system proxy, clear the system proxy set for this test and enable TUN as prompted by the client. Check whether another VPN, network filter or organization policy is managing the same traffic. Grant permissions only in response to this operation. If the system hasn't established the required network state, troubleshoot that first rather than repeatedly updating the subscription. After disabling TUN, test both the apps that need a proxy and local services to confirm traffic has returned to the expected path.
If pages stall after your Mac wakes from sleep, temporarily disable the traffic-handling mode and check that Wi-Fi or Ethernet works on its own. Restore the previous mode and retest with the same node. Run scutil --proxy in Terminal to see the proxy settings reported by macOS, but this doesn't prove that every app follows them. If the problem only occurs after switching networks, check the active network service, old proxy ports and virtual interfaces before changing server settings.
Linux: packages, desktop proxy and TUN
Package formats and processor architecture
Choose v2rayN from the Linux downloads. Debian- and Ubuntu-based systems generally use deb packages; Fedora-based systems generally use rpm. For other distributions, check the supported package format and dependencies instead of renaming the file extension. Run the commands below to check your machine architecture and distribution ID. x86_64 corresponds to x64 on the downloads page; for aarch64, check the arm64 option. The distribution ID tells you how to install the package, not your processor architecture.
uname -m
cat /etc/os-release
Open the downloaded package in your system's software installer. If your desktop doesn't provide an installer, use your distribution's package manager to install the local file: pass the full path to the downloaded package to apt install or dnf install, quoting the path if it contains spaces. Don't mix deb and rpm packages in one installation, and don't use options that force installation while ignoring dependencies. If dependencies can't be resolved, check which library, architecture or repository the error mentions instead of reinstalling the system.
Run the client as your regular desktop user
Launch v2rayN from the app menu as your regular desktop user, then check that the main window and status area look normal. Configuration is usually tied to the user running the app. Switching between a regular account and an elevated account can load different settings or leave files the regular user can't modify. If TUN requires elevated permissions, elevate only the relevant operation; don't run the entire desktop app with elevated privileges all the time. If the app disappears when you close its window, check whether your desktop supports tray icons before starting another instance.
Add a subscription URL under Subscription Group, update it and select an active server. If the update returns a network error, check which proxy settings the desktop browser and client are each using. A subscription page loading in your browser doesn't mean the client's update request follows the same route. If the core reports a port conflict after import, run ss -ltn to check local TCP listeners and compare them with the entry point shown by the client. Don't stop an unknown process until you identify the conflict.
Test desktop apps, command-line tools and the virtual interface separately
Whether a desktop proxy works depends on the desktop environment and how the app reads proxy settings. Some GNOME or KDE apps may use the desktop proxy; command-line tools usually use their own options or process environment. When the client reports that automatic configuration succeeded, test with an app known to follow desktop proxy settings, then verify the listening port with an explicit proxy. Environment variables set in one terminal may not reach apps launched from the desktop, and a new terminal may not inherit temporary variables set in another one.
If you need TUN, turn off the desktop or app proxy used for comparison before enabling the client's TUN feature. Virtual interfaces may be unavailable in containers, restricted environments or managed workstations, even when a desktop is present. On a host where you have permission, run ip link show before and after enabling TUN to compare interfaces, and use ip route show to inspect common routes. The latter shows only the default query scope, so it can't rule out policy routing. If policy routing is in use, also check ip rule show and the route taken by the actual target.
If only graphical apps fail, start with desktop proxy and app settings. If only TUN fails, check permissions, interfaces, routes and DNS handling. If terminal tools still misbehave after you exit the client, check whether they still read old proxy environment variables. Ending a session, clearing test environment variables and restoring desktop proxy settings are separate actions; undo only what you changed. You don't need to reset the device's entire network.
Android: subscriptions, VPN permission and per-app proxy
Installation architecture and client choice
Open the Android downloads. v2rayNG is the first choice and uses the Xray core; v2flyNG is an alternative when you need a V2Fly core. For devices that support 64-bit ARM apps, look for arm64. If the architecture is unclear or the arm64 package is reported as incompatible, check the universal build and system requirements. A 64-bit-capable processor doesn't mean the installed system can run every 64-bit app. Installation may also fail because the system requirements aren't met, storage is low, or the new package's signature doesn't match the installed app.
When you open an installer from a browser or file manager, Android may ask you to allow installs from that source. Grant permission only after confirming the source and that this installation needs it; you can revoke it afterward. If an upgrade fails because of a conflict, don't uninstall the client you're using right away. First check that the source is the same, the subscription still has valid entries and any manual nodes are backed up. The two clients store data separately; installing the other one won't automatically transfer your groups, routes or app lists.
Add a subscription and select a server
Open Subscription Group Settings from the client menu, add a group label and subscription URL, then save and return to the configuration list. Run Update Subscription or the equivalent update action. Menu locations and button names may change; the important distinction is between adding a subscription group and importing a single node from the clipboard. After refreshing, check which group contains the nodes and select the one you want to use. If the node count is unexpected, check whether the list is filtered to another group before investigating subscription compatibility.
Don't assume that an entry one client can parse is a good test case for another. If the subscription contains different transport and security combinations, start with a node the current core explicitly supports. If it fails, note the error category, protocol and time; don't show the subscription URL in group chats or public screenshots. When switching between Wi-Fi and mobile data, retest the same node first, then try another if needed. This helps distinguish a network change from a change on the service side.
VPN interface and per-app coverage
Select a server, then tap Connect on the main screen. The first time you connect, Android asks whether the app can set up a VPN connection. Confirm that the request came from the client you just launched before granting permission. Both clients use Android's VPN interface; desktop steps for Set system proxy don't apply. A connection icon or status indicator only suggests that the interface may be active. Open an app and verify that its traffic reaches the client and gets a response.
First test a browser without per-app filtering, then set up per-app proxying if needed. Check the interface description to understand the current mode: an allowlist sends only selected apps through the VPN interface; a denylist lets selected apps bypass it. Traffic entering the interface still passes through the client's routing rules, so that doesn't guarantee every request from an app uses a proxy outbound. If the browser connects but a target app doesn't, first check whether that app is covered, then inspect its domain and outbound rules.
If the connection drops after running for a while, check whether another VPN is set to always-on and whether Android is restricting the client's background activity. Compare logs from before and after the screen turns off. If your system offers Unrestricted or a similar battery-use setting, change it for this client only if background interruptions are actually occurring, then watch for changes in battery use and stability. Some devices also restrict background launches; menu names vary, so don't follow instructions for another brand blindly. For more on the interface and modes, see v2rayNG Android usage tips.
Verify the connection, read logs and roll back
First identify the traffic entry point
Break the connection into four stages: the app sends a request, the local entry point receives it, routing selects an outbound, and the outbound connects and returns a response. A Connected status usually only means the client started the required service or interface. A page loading in your browser doesn't prove the request went through the proxy; it may have come from cache or been routed directly. Check the client logs alongside the target address and test time so you don't confuse results from separate requests.
On desktop, check the port, listening address and entry type in v2rayN's settings or status bar. HTTP and SOCKS are different application-layer entry points; don't treat them as interchangeable just because both are local. Some setups use a mixed entry point, while others use separate ports, so follow what the current interface shows. If the system has old proxy settings, compare them with the active entry point field by field. On Android, check VPN permission, the active client and per-app coverage rather than applying a desktop port test to all phone traffic.
Compare explicit proxy connections to the same target
These commands are for desktop environments with curl installed. In Windows PowerShell, use curl.exe as the command name. The first command disables curl's proxy at the application layer; the second explicitly uses a local SOCKS entry point. Run the second command as written only if the client provides SOCKS at 127.0.0.1:10808; otherwise use the local address and port shown in the interface. Turn off TUN before comparing. The first command can't bypass traffic already intercepted at the system level.
curl --noproxy '*' --max-time 15 -I https://example.com/
curl --noproxy "" --proxy socks5h://127.0.0.1:10808 --max-time 15 -I https://example.com/
socks5h sends the destination domain to the SOCKS entry point; it doesn't mean every domain will be resolved remotely. What happens next depends on the core's routing and DNS settings. These commands isolate the local entry point; they don't rate the node. If both return a response, check which outbound handled the proxied request. If the target doesn't support HEAD requests, try a regular GET through the same entry point. A rejected method alone doesn't mean the network is down.
Narrow down the problem by where the error occurs
If the error points to a local loopback port, first check that the client is running, listening successfully, and using the right port and protocol. If the logs show a connection attempt to a remote server, check the remote address, port, connection timeout and handshake settings in that order. For connection refused, identify which end refused the connection; it doesn't mean every server is down. For i/o timeout, check whether the timeout occurred during connection, read/write or DNS resolution. If TLS handshakes keep failing, check the system clock and the server name, security settings and transport required by the subscription, then confirm the parameters with your provider. See How to troubleshoot v2rayN logs.
Restore the baseline, then add settings back one at a time
To roll back, first disable TUN enabled for this test, restore the original system proxy, remove any test proxy entered manually in the target app, and check whether the original network can reach the baseline page directly. If it still can't, troubleshoot the network itself or its original managed settings instead of changing the subscription again. Once the baseline is restored, add back one node, one traffic entry point and one routing change at a time. Record each setting, target and result. If a change immediately triggers the issue, undo that last step and retest before drawing conclusions. For a step-by-step review, see the Connected but no internet troubleshooting checklist.
Routing and DNS settings
Separate traffic interception from outbound routing
System proxy, explicit proxy and TUN determine which requests can enter the core. Routing rules decide which outbound handles requests that do. If the system proxy doesn't intercept a process, changing the core's domain rules probably won't affect it. Conversely, traffic can enter the core and still be routed directly. Start with the entry-point logs, then check the outbound tag. If you can't find the request in the logs, revisit the app's proxy settings or virtual interface instead of repeatedly changing rule order.
In v2rayN, open Routing Settings and confirm which rule set is actually active before changing anything. Rules are generally evaluated in list order, so a broad rule near the top can match first and mask later exceptions. Keep a copy of the original rule set and give your test set a distinct name. To check an exception, keep the target and app fixed; don't also change the node or DNS settings. After testing, check a second target to make sure the existing split-routing rules still work. One site recovering doesn't mean other apps weren't sent to the wrong outbound.
Rule fields and a core configuration snippet
The snippet below shows the routing field in an Xray core configuration. It assumes an outbound tagged direct is already defined: the first rule matches only the exact domain example.com, and the second matches the specified private IP range. This isn't a complete client configuration and shouldn't be pasted into a subscription URL field. In the v2rayN GUI, add the corresponding domain or IP condition to a custom rule and select a direct outbound already present in the active rule set. Don't copy just the tag without checking which outbound it refers to.
{
"routing": {
"domainStrategy": "AsIs",
"rules": [
{
"type": "field",
"domain": ["full:example.com"],
"outboundTag": "direct"
},
{
"type": "field",
"ip": ["10.0.0.0/8", "172.16.0.0/12", "192.168.0.0/16"],
"outboundTag": "direct"
}
]
}
}
full: matches only the exact name provided; it doesn't include subdomains automatically. To match the domain and its subdomains, consider domain: instead. outboundTag references an actual outbound; it isn't a protocol on its own. In the example above, AsIs doesn't resolve a domain just so it can match an IP rule. If the destination entering the core is already an IP address, there may be no domain available for domain rules to match. When debugging, check the destination shown in the logs rather than assuming every request uses the same form as the browser's address bar.
DNS diagnosis and a safe order of changes
Apps, the operating system and the core can all participate in DNS resolution. A browser's secure DNS, the client's resolution settings and whether TUN handles DNS can change whether a request reaches the core as a domain or an IP address. They can also make the same domain resolve differently in different apps. When troubleshooting, note the full domain, time and current mode for the failed request. When comparing a direct system connection with an explicit proxy, identify which resolver each one uses instead of comparing only whether the final page loads.
If a domain fails but other addresses for the same service work, check the logs for resolution errors, then see whether the rules use domains, IPs or external category data. Replacing the hostname in an HTTPS URL with an IP address isn't an equivalent test; server-name and certificate matching also change. For local shares, printers or organizational services, check that private addresses remain on the required route. A working public website isn't enough to confirm the setup is correct. Keep the original DNS and routing values, and change one layer at a time. For field definitions, see the Quick Reference.
Common setup questions
The subscription updated, but why are there no active nodes?
Check that the update message refers to the current group, then see whether a search term, group selection or filter is hiding nodes. An update success message only confirms that the client completed a particular fetch or parsing step; it doesn't guarantee the previous active server is still listed. Your provider may have renamed or retired it. Choose another server in the group and check its active status. If the group is completely empty, confirm that the subscription response uses a supported format, then check access permissions, validity and whether you used a management page URL instead of the subscription URL.
Why does my browser work when other apps don't?
First check whether the browser is using the system proxy or its own proxy settings. If a desktop app has its own proxy option, configure it with the protocol and port the client actually listens on. If it doesn't, consider using TUN. On Android, check whether per-app settings exclude the target app. If the logs show the target app's requests but its service still won't load, check which outbound handles the domain and whether DNS works; there's no need to reinstall the client. Also confirm the app can sign in normally before testing.
Can I enable the system proxy and TUN at the same time?
Different systems, clients and rule sets handle overlapping traffic differently; turning on both doesn't tell you which path an app will use. For a first setup or troubleshooting, a single entry point is easier to test consistently. When switching from system proxy to TUN, clear the system proxy set for this test before enabling TUN. To switch back, disable TUN, check that the network works, then configure the system proxy. If your device has an organization-mandated proxy or VPN, don't disable it without checking the coverage and management requirements. When you're done testing, restore the original settings rather than clearing everything.
How can I tell whether the node or my local setup is at fault?
Keep one device, one network and one test target fixed. After confirming that the local entry point receives requests, compare two independent nodes from the same group. If one fails and the other works, start by checking the failed node's status and settings. If several nodes fail at the same local stage—for example, the local port refuses every connection—troubleshoot the local entry point. If they all fail during outbound DNS resolution, check DNS and network conditions. Multiple failed nodes don't prove that every server is down; they may share a network dependency, resolution path or authentication state.
What should I save before switching clients or reinstalling?
Record your subscription group names, active routing group, traffic-handling mode, local listening ports and any manual nodes. If the client offers an export function, save the configuration only in a secure location; exports may contain addresses and access details, so don't upload them to a public drive or chat. When moving to another client, reimport subscriptions and restore routing settings individually rather than assuming it can read the old configuration directory. Confirm the migration by checking that the entries are visible, the right node is active, the local entry point works and traffic is routed as expected—not merely that the old directory copied successfully. For client differences, see our client comparison.
What information should I provide when asking for help?
Include your operating system and architecture, client name and displayed version, active core, traffic entry point, scope of the failure and when it first started. Mention whether you recently updated a subscription, switched networks or enabled TUN, and whether you can restore the previous network state. Share only log lines relevant to the failure and redact server addresses, subscription URLs and credentials. Check screenshots for account details or internal network information, too. A comparison such as “the same browser and target work with the system proxy but fail with TUN” is more useful than “it never connects” and helps narrow down where to start troubleshooting.