V2Ray Setup Guide for All Platforms

For your first connection, follow the Getting Started guide to import a subscription, enable a proxy, and verify the connection. If the client is already installed, or you need details on packages, system-wide traffic handling, routing, or DNS, go straight to the relevant section of this guide. When troubleshooting, change one setting at a time and keep the configuration that reproduces the issue.

Before you begin: packages, subscriptions, and verification

Know the difference: client, core, and subscription

For desktop, start with v2rayN. On Android, try v2rayNG, which uses the Xray core. Consider v2flyNG only if your subscription provider specifically requires the v2fly core. The client manages subscriptions, selects nodes, and connects to system traffic; the core handles the connection. A subscription is a configuration link from your provider, usually returning a set of importable nodes. An installed package may run correctly even if its core does not support every transport or security option in your subscription.

Choose a package for the architecture your operating system can run, not the device's product name. Check system information on desktop devices; on mobile, also consider which architectures the operating system makes available to apps. Choose a new package when switching devices—don't copy the entire program folder from an old machine. If your provider offers multiple subscription formats, look for one intended for your client. Two clients accepting the same link doesn't mean they'll generate identical node configurations.

Clients and package requirements for four platforms
PlatformClientWhat to check when choosing a package
Windowsv2rayNx64 system; desktop or classic WPF edition
macOSv2rayNApple Silicon or Intel
Linuxv2rayNDistribution package format; x64 or arm64
Androidv2rayNG / v2flyNGarm64 or universal; choose a client compatible with the core

Keep the original details so you can import them again

Store your subscription URL and the provider's instructions somewhere only you can access. Subscription URLs may contain identifying information; shared node links, QR codes, and exported configurations may also include connection credentials. Don't post them in public support tickets or submit them to untrusted online converters. For your own notes, record only the group alias, protocol, transport, and last update time. Before syncing to a new device, check whether your provider limits the number of devices connected at once so you don't mistake a device limit for a configuration issue.

Treat subscription updates and node connections as separate steps. An update fetches configuration from the subscription service; a connection uses a configured server. A successful update only means the content retrieved this time could be parsed. A node may still fail to connect because its transport options don't match, certificate verification fails, or the network can't reach it. If your provider changes the subscription URL, update the address on the existing group, then refresh it manually. Avoid creating multiple groups with the same name—you could easily select an outdated one.

Follow a repeatable test sequence

Before enabling a proxy, confirm that a site you use regularly opens on your current network. If the network requires a sign-in, complete that first, then start the client. Check your system's date, time, and time zone; enable automatic time syncing if possible. Import one group, update it manually, and select a node known to work. Check the core logs for startup errors, then enable the platform's connection method. Finally, use the same app to visit the same destination and compare the results before and after startup.

For your first desktop test, verify the system proxy. On Android, start with the system VPN connection. Don't enable custom DNS, change routing rules, or switch cores at the same time. If the test fails, note whether the update failed, the core didn't start, or the app couldn't access the network. When moving from an old device, verify one connection on the new device before restoring routing rules and scheduled updates one at a time. This avoids carrying over old configuration issues.

Windows: Install v2rayN and configure the system proxy

Choose the desktop or classic WPF edition

Go to Windows downloads and check the system type in your device settings against the package label. The desktop edition uses a cross-platform interface with a layout similar to other desktop systems; the classic WPF edition has a familiar Windows interface. Install just one. If both editions launch at startup, they may compete for the same local port or overwrite each other's system proxy settings when you exit.

Complete the installation wizard. If your package needs to be extracted, extract the entire folder to a location your regular account can write to, then launch the app from there. Don't run it from the archive preview window. If startup reports a missing runtime, follow the instructions for your current package and the download page; don't copy components from another program folder. Before migrating settings, exit the client normally, then export or back them up using a method the client supports. Don't overwrite a new version with an old folder that no longer starts.

Import a group and check that the core starts

Open the subscription group settings, add a group, enter an alias that identifies its source and the subscription URL, then save and update the group. Return to the main window, switch to that group, select a node, and set it as the active server. Seeing a node in the list doesn't mean it's enabled; check the active server indicator and startup logs. If the update returns nothing, confirm that you selected the right group and subscription format, then check the update logs. Don't immediately change ports or clear existing groups.

Check the local listening address and port in the settings. For local testing, keep the loopback address; use the port shown in your actual settings. If the logs say the address is already in use, find out what's listening first. The PowerShell command below uses a common port as an example; replace it with the port shown in the app before running it. The command lists the listening address and process ID without changing any settings. Use the Details tab in Task Manager to identify the process; don't terminate an unfamiliar system process.

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

Verify the system proxy before trying TUN

Select automatic system proxy configuration from the tray menu, then check the address and port in Windows network proxy settings. Apps that use the system proxy usually read these settings; browsers and tools with their own proxy configuration may not. First, make a new request from a browser known to follow system settings, then check whether the client logs the connection. Existing browser tabs may reuse old connections. Test in a new window, or quit and restart the browser normally if needed.

If only apps that ignore the system proxy need access, first check whether they let you enter a proxy address in the app itself. Use TUN to handle a wider range of traffic only when necessary; follow the desktop TUN checklist and grant the permissions the client requires. For the first test, restore the system proxy to its baseline to avoid overlapping connection methods. If a work computer blocks permission changes, follow your organization's process. Don't disable management policies or treat administrator access as a routine fix for connection failures.

After waking from sleep, switching Wi-Fi networks, or an unexpected exit, if the network stops working when you close the client, check whether Windows still points to a stopped loopback port. Restore the original proxy first, then test basic connectivity. If your organization uses an automatic configuration script, restore its policy rather than just turning off the manual proxy. Reinstalling often doesn't clear a proxy setting left at the system level. For details on extracted folders, runtimes, and first launch, see the v2rayN first-install checklist.

macOS: Install v2rayN and configure network services

Download the build for your chip and launch it for the first time

Open About This Mac from the Apple menu. Choose the Apple Silicon package if the device shows an Apple chip, or the Intel package if it shows an Intel processor. Go to macOS downloads and select the matching disk image. Once it mounts, follow the window instructions to copy the app to Applications, then launch it from the copied location. You can eject the disk image once the app opens successfully. Don't keep launching the app from the mounted volume; its shortcut won't work after you eject it.

When macOS warns you the first time you open the app, distinguish a routine confirmation from a security policy block or an app that won't start. Check the package source, chip compatibility, and system requirements. Ask your administrator about restrictions on managed devices. Don't disable system-wide security checks just to open the app. If the interface opens but the core process fails to start, check which program and path the logs identify. If the issue began after a system upgrade, check compatibility notes for the new system and package before changing existing settings.

Update the subscription and check the active connection

Add a group from the subscription menu, enter an alias and URL, save it, and update it manually. After the entries appear, select an active node and check that the core started. When migrating an old configuration, keep the subscription details you can reimport and only a few custom rules. Don't copy the core binaries, absolute paths, or launch helpers from another device. Paths and chip architectures can differ, and even if the node text is identical, the program it calls may not run.

If a group refresh returns an HTTP error, first check subscription access and whether the current network can reach the URL. Don't send the full link to someone else for testing. If the refresh succeeds but the connection handshake fails, check that the active node's protocol, transport, and security settings match. If most nodes in the same group connect, narrow the problem down to the failing entries. Don't immediately reset network locations or change system-wide DNS settings.

Check the system proxy for the active network service

After enabling the system proxy in the client, open the active network service under Network in System Settings and check its proxy details. Wi-Fi and Ethernet may be separate services; if the setting was applied to an inactive service, apps won't use the expected proxy. After connecting or disconnecting a dock, or switching between Wi-Fi and Ethernet, verify the active service and check that the client's local port is still listening. The command below only reads the system proxy status. If the results include an organization-configured address, don't share the full output publicly.

scutil --proxy

Check the enabled type, host, and port in the output; don't rely on seeing the word “proxy.” The client port must match the system's configured destination, and the proxy type must also match. If a browser works but another app doesn't, check whether the app has its own network settings or is reusing a connection opened before the proxy was enabled. Change one setting and reopen the app to test. You don't need to enable every category of system proxy.

How to revert after switching networks or enabling TUN

If you need to handle apps that ignore the system proxy, first record the current network service, proxy, and DNS settings. Then check the client's TUN options and required system permissions. After enabling it, run two tests: a regular web request and access to a local resource that should remain available. A working webpage doesn't mean local traffic is unaffected. If your organization's intranet or a local device suddenly becomes unreachable, turn off TUN and restore the previous connection method to see whether the issue goes away. Don't grant permissions repeatedly as a substitute for tracing routes.

If you lose connectivity after waking from sleep, first check whether the default network changed, then check the loopback listener and proxy settings for the active service. When you close the client, restore the previous proxy state rather than clearing everything. If the problem occurs only on one Wi-Fi network, check whether it requires a sign-in or has its own proxy policy. This helps separate a network-specific configuration issue from an installation problem and avoids unnecessary changes to other networks.

Linux: v2rayN package formats, desktop proxy, and TUN

Choose a package based on your distribution and architecture

Check your distribution in system information, then choose v2rayN from Linux downloads. Systems using Debian-based package management generally use deb; systems using RPM package management can use rpm if they meet the package's dependencies. Matching package formats don't guarantee compatible dependencies, especially on older distributions. For architecture, x86_64 commonly corresponds to x64, and aarch64 to arm64. A container or compatibility layer may report a different environment from your actual desktop session, so check the system where you'll run the client.

cat /etc/os-release
uname -m

Install the package using your distribution's software installer or a package manager that supports local files, and let it report dependency conflicts. If the architecture doesn't match, return to the download page and choose the right package. If dependencies are unavailable, check whether your distribution meets the requirements instead of forcing the installation. Installation may require authorization; run the client from your regular desktop session. Launching the entire app as an administrator can change its configuration directory or file ownership, leaving your regular account able to read settings but unable to save them.

Import a subscription and check the core listener

Launch v2rayN from a regular desktop session, create a subscription group, enter an alias and URL, update the group, and select a node. Before switching, check which core and transport settings the node requires. Importing creates a node entry; you also need to check that the core process accepts its parameters and starts listening. If the app won't open, check its startup messages. If the interface opens but the core won't start, check parameter parsing, program permissions, and the listening port. Don't assume every failure means the subscription has expired.

Start by checking ports on the local machine. On systems with ss installed, the command below checks local TCP listeners. Replace the example with the actual port shown in the app. If there's no output, check whether the core started before adding any firewall rules. A listener only confirms that a local entry point exists; it doesn't prove the remote connection works. If it's listening on a wider address than expected, check whether LAN access was enabled by mistake, restore a local-only address, then continue testing.

ss -ltn 'sport = :10808'

Check whether the current desktop session uses the proxy

Desktop environments store system proxy settings in different places. The same client button may not make every session, browser, or background service use the same settings. After enabling the system proxy, check the proxy settings in your current desktop environment, then make a new request from an app that follows them. Terminal programs may read proxy variables from their own process environment or use their own settings; another terminal session won't automatically inherit temporary variables. To troubleshoot, set the right proxy type in a single test program instead of writing a global variable that affects every process.

If a browser uses the proxy but a command-line request connects directly, that doesn't necessarily mean routing is wrong. First check whether the request reached the core, then confirm whether it supports the HTTP or SOCKS entry point. You can't identify the type from the port number alone. Programs launched by a service manager run in a different environment from your desktop session, so a successful browser test doesn't prove that a service is using the proxy. If a single app meets your needs, keep the configuration scoped to it so it's easier to undo.

Check TUN permissions and routes

Use TUN only if needed. Confirm that your system supports a virtual network interface and that the client can get the required permissions through your distribution's mechanism. Check routes before and after switching; if you have multiple network interfaces or use a virtual machine, compare local subnets that need to remain accessible. The commands below inspect IPv4 routes and policies without changing the system. If your current network also uses IPv6, check its IPv6 routes too. If office or virtual machine traffic is affected, turn off TUN to verify the cause instead of immediately replacing the default route.

ip route show
ip rule show
ip -6 route show

If the network still doesn't work after you exit, check that the virtual interface and client process have stopped, whether the desktop proxy remains set, and whether the network has returned to its original route. On devices managed by a network service, restore settings through that service rather than manually overwriting generated files. If a reboot temporarily fixes things, note what triggered the issue: the client exit sequence, waking from sleep, or a network change. The next time it happens, you'll be able to capture comparable state while the issue is still present.

Android: v2rayNG, v2flyNG, and VPN connections

Choose a client and installation package

Start with v2rayNG from Android downloads. Choose v2flyNG only if your subscription provider requires the v2fly core; don't run both clients during your first test. If you've confirmed the system supports arm64, choose the matching package. If you're unsure, or the processor supports arm64 but the system only runs apps for another architecture, check whether the universal build is suitable. If the installer reports incompatibility, check system requirements and available storage as well as architecture. Changing subscriptions won't fix an installation error.

When you open an installer from a browser or file manager, the system may ask you to authorize that source. Grant only the permission needed to open a known package, then revoke it if you like. If an update reports an installation conflict, check whether the installed app came from another distribution channel or a different user profile. Before uninstalling and reinstalling, keep the original subscription URL and any essential settings; local groups, custom rules, and selected items may be removed with the app.

Add a subscription, then start the VPN

Add a group in subscription management, enter an alias and subscription URL, save it, then update it. A single shared link and a full subscription are different entry points: import a single node using the client's single-item option, and refresh subscriptions from a group. Make sure you're viewing the group you just created, select an entry, then start the connection from the main screen. Menu labels may vary by version, but saving the URL, fetching entries, selecting an entry, and starting the connection are four separate steps.

The first time you start a VPN, Android asks whether to let the client establish a local VPN connection. Confirm the request came from the client you just opened, then allow it. A VPN icon in the status bar only confirms that the VPN connection was established; it doesn't prove the selected node is connected. Make a new browser request and check the client logs. If another app already manages the VPN, check whether it can be paused. Don't remove connections managed by a work profile or device policy yourself.

Tell apart background stops, per-app restrictions, and network changes

If the connection works with the screen on but drops after it turns off, first check whether the connection service is still running, then review the system's app battery and background policies. Reproduce the issue once and note how long it takes to disconnect, whether the notification remains, and whether it reconnects after unlocking. Change background permissions for this client only if you confirm the system stopped its service. Don't remove battery restrictions from every app, and don't treat a persistent notification as proof the remote connection is still working.

If only one app can't connect, check whether per-app proxying is enabled. Confirm whether the current mode includes or excludes selected apps; don't rely on whether an app is checked in the list. After changing it, rebuild the connection as prompted and make a new request from the target app. Also distinguish Android's “Always-on VPN” from “Block connections without VPN”: the first keeps the VPN active, while the second affects other network access when the VPN disconnects. Don't use either option as a fix before you've verified the initial connection.

If the connection fails after switching from Wi-Fi to mobile data, retest on the original network, then make a new request on mobile data. Existing connections may break when the network changes, and the system may restrict mobile data for some apps. If the issue occurs only when the screen turns off or the network changes, check system policies first. If the same node's handshake fails on both networks, investigate its configuration instead. For help balancing battery life and background reliability, see v2rayNG battery optimization and background settings. Change one permission at a time and note the result.

Routing and TUN: traffic entry, rules, and exits

First check whether traffic reaches the core

System proxy and TUN determine how traffic enters the client. A system proxy provides settings that apps can choose to use—or ignore. TUN uses a virtual network interface and system routes to receive matching traffic. Routing rules determine which exit handles traffic after it's received. Switching to global proxy rules won't automatically connect apps that ignore the system proxy; enabling TUN doesn't mean every connection it receives is forwarded remotely.

When troubleshooting an app that isn't using the proxy, check the logs for the moment it makes a new connection. If the core has no matching entry, check the system proxy, the app's own settings, or system routes. If there is a log entry but it shows a direct connection, check the rules. If the expected exit was selected but the connection failed, check DNS and the handshake. The log level may affect how much detail is recorded; raise it one level temporarily if needed, then restore it after reproducing the issue. Distinguish these three stages before rewriting all your rules when the core hasn't even seen the request.

Start with a narrow rule and test it

When using a built-in routing scheme, first read its match conditions and default exit. Schemes with similar names may behave differently, so don't guess from the name alone. For a custom rule, start with one specific domain or subnet and confirm whether the core receives a domain or an IP address. A domain rule matches the domain available for routing—not the full URL entered in a browser. In most cases, don't include the protocol prefix, path, or query parameters in a domain match.

When traffic matches multiple rules, routing rules in commonly used cores are evaluated in order; the first match wins. Put the specific case you're testing before broader rules, and check which exit is used when nothing matches. A proxy group alias isn't necessarily the actual outbound identifier, and you shouldn't paste a configuration snippet for another core directly into the current rule editor. After changing cores, test a simple rule first, then restore advanced conditions from the previous setup one at a time.

Local printers, shared folders, and internal services usually have their own access paths. Confirm the local domain, address range, and enterprise network requirements in use, then configure direct access or a system-level exclusion as needed. These are not always handled at the same layer. Test a local resource and a regular webpage. If the webpage works but the shared resource doesn't, check whether local traffic entered the virtual interface. If it reached the core, check which exit the core selected.

Enable desktop TUN in a way you can undo

First verify that the same node works with your existing connection method. Save the baseline system proxy and routes, then check the client's TUN implementation and permission requirements. Turn off the system proxy used for testing, start TUN, then test a regular webpage, an app that ignores the system proxy, and any local services that must remain accessible. Use new requests rather than reusing long-lived connections established before startup. If all requests time out with TUN enabled, turn it off and restore the baseline. Confirm the previous connection method still works, then check the virtual interface and system routes.

When a virtual interface and another VPN run at the same time, they may override each other's default routes, destination subnets, or DNS paths. Don't enable multiple traffic-handling features at once as a fix. Switching between Wi-Fi and Ethernet can also change the default gateway; when reproducing the issue, note the connection method, destination type, and client logs. If it happens only after a normal exit, check whether the original proxy and routes were restored before deciding whether to restart the app. A reliable way to undo changes is more useful for diagnosis than stacking settings to make one webpage load.

DNS settings: find out what resolves each name and where

Identify where each request is resolved

First identify whether the problem concerns the subscription service, the node server, or the domain you're trying to visit. These addresses may be resolved at different stages. The client usually fetches subscription updates; the node server's domain must resolve before a remote connection can be established. The target domain may be resolved by the app, system, core, or remote endpoint, depending on the connection method and outbound settings. If you only see “DNS resolution failed,” find the corresponding request in the logs before changing system-wide DNS.

An app may pass the proxy a resolved IP address or a domain name. If the core receives only an address, domain-based routing rules may not work. If it receives a domain, an IP lookup may not be needed before choosing an exit. Before using a domain-based routing strategy, distinguish between matching by domain and matching a subnet using a resolved address. Traffic sniffing may identify domains for supported protocols and conditions, but it can't recover the domain for every connection or replace a correct DNS path.

Verify DNS settings with minimal changes

For the first troubleshooting test, keep the DNS settings that worked before. On the same network and in the same app, test a regular domain and an internal domain that must remain accessible; they may correctly resolve through different services. If internal domains resolve only on your organization's network, don't switch to an external service just to make the settings uniform. If your browser supports encrypted DNS, note whether it's enabled, since its results may differ from the operating system's. After a change, account for app and system caches and test with a new request instead of relying on an old tab.

This is an example dns section for a V2Fly core configuration; localhost means to use the system resolver on this device. It's a JSON snippet to merge into an existing core configuration, not a complete standalone configuration, and it doesn't set the DNS server address to a loopback address. Graphical clients usually generate the final configuration from their interface, so change the relevant setting there rather than overwriting the original file with this snippet. If you use a different core, check its configuration fields and version support before making changes.

{
  "dns": {
    "servers": ["localhost"]
  }
}

Troubleshoot DNS loops and address-family differences

After enabling TUN or custom DNS, check whether requests to the resolver are being captured by the same connection method again. If the node server's domain can only be resolved after the proxy connects, startup may get stuck waiting on itself. Compare the first error in the logs with the system's original DNS settings to find which path handles the initial lookup. Revert recent changes first, then restore DNS-related settings one at a time. Don't change DNS, routing rules, and cores all at once; even if things start working again, you won't know which change helped.

The same domain may have both IPv4 and IPv6 addresses. Getting a DNS result doesn't mean the current network can reach every address. If it works at home but times out on mobile data, check the actual connection address in the logs and whether the network supports that address family. Don't test a domain configuration by connecting directly to a website's HTTPS IP address: the certificate name, server name, and domain you're visiting may still need to match. Use the same domain and check whether it failed to resolve or resolved but couldn't connect.

If only one browser reports a DNS error, compare its proxy and encrypted DNS settings first. If every app fails, check system DNS and the current network entry point. If the issue occurs only with TUN enabled, compare the DNS paths and local service access with TUN off and on. When you're done, undo temporary settings you don't need, keep only changes that clearly fixed the issue, and note why. This helps prevent experimental settings from being mistaken for required configuration when you change networks.

Common configuration issues: from local status to remote connection

Subscription update fails or no nodes appear afterward

First confirm you're editing the current group and check for extra spaces or a truncated URL. If the logs show an unauthorized or forbidden response, ask your provider to confirm the URL's access and status. If content arrives but can't be parsed, check whether it's a login page, an error page, or a format for another client. If you previously needed an old node to update this URL, keep a known-working configuration before updating and check whether the update uses a direct connection or the current proxy. Don't delete all old entries until you've confirmed the new group works.

If the update succeeds but you still see old content, check the list filters, group selection, and active server. Scheduled updates and manual updates are different; run a manual update during testing and check its timestamp and result. If new entries appear but the active node hasn't changed, select the intended entry again and make a new request. If only one group is affected, isolate that group rather than resetting the entire client.

Core startup errors, port conflicts, or insufficient permissions

Find the first important error at startup. If an address is already in use, follow the platform section to determine whether it's an old client instance, an incorrect listening address, or another program using the port. If it's safe to change, update the listening port in the client and any apps manually configured to use the old one. If a file can't be found or executed, check the package architecture, program path, and file permissions. For invalid parameters, disable the most recently added rule or custom setting and test a simple node. Each error concerns a different layer; reopening the system proxy won't make the core accept invalid parameters.

Core is running, but connections time out or the handshake fails

First confirm that the request reached the correct local entry point, then check the system time and whether the active node matches the core. For a handshake failure, compare the protocol, transport, and security settings with your provider's instructions. Don't disable certificate verification to hide an error. For a timeout, determine whether DNS resolution failed, the connection wasn't established, or the connection was established but no expected response arrived. Compare with a known-working node using the same app and connection method, or keep the node unchanged and test on another network you're authorized to use. Change one condition at a time.

If browser and client speed tests disagree, check what each one tested. A speed test may verify only a short section of the selected connection path; it doesn't replace a real app request. If one webpage works but video, meetings, or another app doesn't, check whether they use the same entry point and protocol, and whether the connection method handles their traffic. A successful test doesn't prove the whole device and every app are using the same configuration.

Network doesn't recover after stopping the client

On desktop, check whether the system proxy still points to a stopped local port, then confirm TUN has exited and the default network and DNS have returned to their baseline. On mobile, check Always-on VPN and Block connections without VPN. Restore only the settings changed during this session; don't remove organization-managed proxies or other network settings. If the proxy is restored but regular network access still fails, test without the client and troubleshoot network sign-in, address assignment, or basic connectivity. Don't add another routing rule.

How to prepare a useful, reviewable troubleshooting report

Record the operating system, client and core types, connection method, behavior before and after the change, time of reproduction, and a few log lines before and after the error. If the issue occurs only when switching networks, turning off the screen, or waking the device, include the trigger sequence and app state. Before sharing diagnostic screenshots, hide subscription URLs, account details, server addresses, and internal domains. Note which changes you've reverted and whether everything worked before the change. This helps others distinguish connection issues from changes introduced during testing.

To troubleshoot a specific error message, see How to diagnose V2Ray logs. For common installation and usage questions, visit the Help Center. To repeat the first-connection setup, return to the subscription import steps in Getting Started and establish a new baseline with one group, one node, and one connection method.