All Platforms · Installation & Setup

V2Ray Setup Guide for Windows, macOS, Linux, and Android

Setting things up for the first time? Follow the Quick Start Guide to import a subscription, connect, and verify it works. This page is a platform-by-platform reference: start with the section for your device, then refer back to subscriptions, proxy settings, and troubleshooting for issues that span platforms. v2rayN is the recommended choice for desktop; v2rayNG is recommended for Android.

Before You Start: Builds, Subscriptions & Permissions

Quick reference
ItemWhere to checkRecommendation
OS and architectureSystem informationCheck the architecture before choosing a build
Subscription URLProvider account or documentationCopy the full URL; never share it publicly
First connection testClient logs and browserTest one node first, then adjust how traffic is routed

Choose a build by architecture, not device family

On the Download Clients page, choose your operating system, then check the architecture and package format. x64 and x86-64 refer to the same architecture; arm64 may appear as AArch64 in system information. You can’t identify the right build by OS name alone. A desktop processor’s brand doesn’t determine the package name either—for example, a Linux package labeled amd64 usually works on Intel processors with the same architecture. The download page may list only some architectures for a platform. If there’s no matching option, check the OS type and release notes rather than using a package for another platform. For older devices, also check that the OS version meets the client’s minimum requirements.

Know the Difference: Subscription, Node & Proxy Endpoint

A subscription URL retrieves a list of nodes. Each node stores protocol, destination address, port, and transport settings. A local proxy endpoint lets apps on your device send traffic to the client. These are three different things. A successful subscription update means the client received data it could recognize—not that every node can connect. Likewise, if the subscription site is temporarily unavailable, already imported nodes may still work. When documenting an issue, specify whether the failure occurs during subscription update, core startup, or access to a destination. Then troubleshoot the right layer.

Before importing, check whether you have a subscription URL or a single-node share link. Add the former as a subscription group and update it manually; import the latter from the clipboard or by scanning its QR code. Node links and subscription URLs may contain access credentials. Don’t paste them into online parsers or share screenshots containing QR codes in public discussions. Name groups by source or purpose to distinguish manually added nodes from subscription nodes. Before editing a subscription, note the active node and group. An update may rebuild the entries and overwrite changes to a subscribed node’s settings.

Establish a baseline before changing settings

Before you start, note the current system proxy settings, whether another network-routing tool is running, and the client’s current routing mode. Corporate proxies, fixed scripts, and manual exceptions may be intentional; don’t treat them as settings that must be removed before installation. Choose a familiar HTTPS page as a consistent test target. Keep the network, node, and browser the same; check how it behaves with routing disabled, then change just one setting. If the browser has a proxy extension or its own proxy configuration, check whether it overrides system settings before testing. On desktop, there’s no need to rush into TUN before the system proxy test passes. On Android, routing uses the system’s VPN permission.

For the first connection test, don’t enable custom DNS, manual routing rules, and launch at startup all at once. Once the connection works, add only the settings you actually need, one at a time, and repeat the same test after each change. Check both client logs and the page itself: a changed tray icon only shows that the interface state changed, and a page may load from cache. Reload the page and compare the logs from the same time to confirm the request used the expected endpoint. If you need help, share the platform, package type, failure stage, and redacted error details—not a full configuration export.

Windows: v2rayN Desktop and WPF Editions

Quick reference
SettingOptionsRecommendation
EditionDesktop / WPFStart with Desktop for a new setup; choose WPF if needed
System proxySet automatically / ClearFirst test apps that read the system proxy
TUNEnable / DisableEnable only after checking permissions and routing needs

Choose an edition and installation location

Go to the Windows downloads and choose either the v2rayN Desktop or classic WPF edition. Desktop uses a cross-platform interface, making it easier to carry familiar workflows across desktop operating systems. WPF suits users who prefer the classic Windows interface or rely on existing workflows. The main differences are the interface and runtime environment—not the type of subscription URL. When switching editions on the same PC, fully exit the old client from the system tray first. This avoids two cores competing for local ports or two processes repeatedly changing the system proxy.

If you downloaded an archive, extract it fully to a directory your account can write to, then run the main program. Don’t launch it from the archive preview. If you downloaded an installer, follow its prompts, then open the app from the Start menu or its shortcut. If startup fails because a runtime component is missing, note the runtime name and architecture from the error and install what the edition’s documentation specifies. Don’t download a matching library file from search results and drop it into the app directory. If your organization’s security policy blocks execution, ask your device administrator for approval rather than disabling protection to force installation.

Import a subscription and configure the system proxy

Open the subscription group settings, add a name and the full subscription URL, save, then update that group. Once nodes appear, select one and set it as the active server. Check the logs for core startup or port-binding errors, then choose “Set system proxy automatically” from the tray menu. Check the proxy status in Windows network settings and visit your fixed test target in a browser. If the system proxy is set but the browser doesn’t use it, check for a browser proxy extension, app-specific network settings, or managed policies. Closing the main window often just minimizes the client to the tray; it doesn’t exit the app or restore the previous system settings.

Troubleshoot TUN, port conflicts, and leftover settings

If you need to route traffic from apps that ignore the system proxy, note the current configuration first, then grant the permissions TUN requires as prompted. If initialization fails, check the logs to distinguish a virtual interface creation error from a routing change or core startup failure. For an isolated test, exit other clients that route network traffic. Don’t leave two routing tools competing for the same default route. After enabling TUN, check that local network resources and work services are still reachable as expected. If more traffic is being routed than intended, disable TUN to restore the baseline, then adjust the routes separately.

Use this PowerShell command to check TCP listeners. The number is a common local SOCKS port and is only an example; use the value shown in the client if it differs. Match OwningProcess in the output with the process ID in Task Manager. No output means only that no TCP listener was found on that port; it doesn’t tell you whether a remote server is online.

Get-NetTCPConnection -State Listen -LocalPort 10808 -ErrorAction SilentlyContinue

If the port is already in use, identify the process first: it may be an old core, another local service, or the current client. If you change the listening port, update any apps where you entered the address manually. If web access starts failing only after the client exits, check whether the system proxy still points to a stopped local proxy. On devices that use a corporate proxy, restore its original settings rather than clearing everything. For more on choosing an edition and installing it, see Installing the Windows Desktop and WPF Editions.

macOS: Choose a Build by Chip and Check Network Services

Quick reference
ItemWhere to checkRecommendation
ChipAbout This MacChoose arm64 for Apple silicon, x64 for Intel
System proxyProxy settings for the active network serviceRecheck after switching network services
TUNClient controls and logsTest permissions and routing separately

Move the app to Applications before opening it for the first time

Open “About This Mac” from the Apple menu to check whether your Mac has an Apple chip or an Intel processor, then choose the matching v2rayN disk image from the macOS downloads. Don’t rely on the year you bought your Mac, or try to adapt a native build to a different architecture. Open the downloaded image, follow the prompt to copy the app to Applications, launch the copy, then eject the image. Running the app from the mounted image can make it hard to tell which copy is launching or replacing. If you have multiple copies, quit the old one and make sure you open the copy you just installed.

If a first-launch alert appears, identify whether it reports an incompatible architecture, an outdated OS, an unrecognized source, or a device management restriction. These require different responses. After confirming the source and device policy, use only the system’s approved per-app authorization process. Contact your administrator for organization-managed devices. Don’t change app security settings system-wide. If the app opens but its core won’t start, check the logs for an execution permission, runtime component, or configuration parsing issue. An open window alone doesn’t confirm a successful installation.

Import a subscription and check the active network service

In v2rayN, create a subscription group, paste the full URL, save it, and update it manually. Select an active node, check the local listener, then enable automatic system proxy configuration. In System Settings, open Network, select the active Wi-Fi or Ethernet service, and open its details to check Proxies. Proxy settings are stored per network service. If both services are listed, don’t check only the one at the top. Menu names can differ by OS version or interface language; use the settings shown for the active service.

If the client behaves differently after you switch from an office Ethernet connection to home Wi-Fi, recheck the Wi-Fi service’s proxy settings and confirm the client applied them. Also check whether the network requires web-based sign-in; a failed subscription update at that point doesn’t necessarily indicate a node problem. These two commands only read network status: the first lists network service order and maps services to devices; the second shows a summary of current system proxy settings. If the proxy is enabled, compare its local port with the one shown in the client. A correct summary still doesn’t guarantee that every app will use the proxy.

networksetup -listnetworkserviceorder
scutil --proxy

Verify TUN and check the connection after sleep or network changes

For apps that ignore the system proxy, if your build supports TUN, first disable the system proxy for comparison, then enable TUN in the client and grant permissions when prompted. Check interface initialization, a request to your fixed test target, and local resources that should remain directly reachable. If the device already has a VPN, proxy configuration, or managed network filter, don’t disable organization settings without permission. Test separately on a network and device where you’re allowed to do so. Existing connections may not reconnect immediately after switching modes; quit and reopen the test app or start a new connection rather than checking a page that was already open.

If connections fail intermittently after sleep or a network change, note the interface in use before sleep and the one actually active after wake, then check whether only old connections are affected. If new connections fail too, check that the client core is still running, the network service proxy points to an active listener, and TUN has been re-established. To restore connectivity, disable the relevant mode in the client first, then check the active network service. Don’t reset all network preferences. Once the issue is reproducible, decide whether to enable launch at login. Setting up auto-start too early can make leftover settings and startup-order problems harder to tell apart.

Linux: deb, rpm, and Desktop Sessions

Quick reference
ItemOptionsRecommendation
Package formatdeb / rpmChoose based on your distribution’s package manager
Environment proxyDesktop proxy / process variablesDistinguish GUI apps from terminal programs
Virtual interfaceTUNCheck interface support and permissions first

Install for your distribution and processor architecture

Debian and Ubuntu generally use deb packages; Fedora and openSUSE use rpm. An rpm package isn’t guaranteed to have the same dependencies across distributions. Open the Linux downloads, check the supported systems in the release notes, then choose x64 or arm64. Run uname -m to check the machine architecture and cat /etc/os-release to identify the distribution. If you run these commands in a container or on a remote host, they show that environment—not necessarily the desktop where you plan to run the GUI client. Don’t add another distribution’s software repositories just to install a package.

When possible, open the local package with your desktop’s software installer. If you need to install from a terminal, the commands below are for Debian-based systems, Fedora, and openSUSE respectively; use only the one for your distribution. The examples assume the actual package is in the current directory and has been renamed to the short filename shown. You can also substitute the full path; quote paths that contain spaces. The package manager should report missing or conflicting dependencies. Don’t bypass those checks by ignoring dependencies.

sudo apt install ./v2rayn.deb
sudo dnf install ./v2rayn.rpm
sudo zypper install ./v2rayn.rpm

Import and test from your everyday desktop session

After installation, open v2rayN from the app menu using your everyday account. The administrative privileges used to install the app don’t mean you should run the GUI as an administrator. Use your regular account to add a subscription group, update it manually, select an active node, and check the logs to confirm the core and listener are ready. If the app isn’t in the menu, first check that the installation completed, then refresh the desktop session and check again. Don’t launch the app as an administrator from another user’s configuration directory to work around a path or permissions issue.

GNOME and KDE Plasma may manage system proxy settings through different interfaces, and terminal programs may read only process variables or their own configuration. Some apps read proxy settings only at startup, so restart them to test changes to the desktop proxy. If a browser works but a package manager doesn’t, find out which proxy source the package manager uses. An administrator process may not inherit the regular user’s environment variables. The command below checks only the local listener; it doesn’t change desktop or terminal proxy settings. If the port shown in the interface differs, replace the value in the command.

ss -ltn 'sport = :10808'

Check the virtual interface and launch-at-login setup

Before using TUN, confirm that the system provides /dev/net/tun and check that the permissions requested by the client have been granted as described in the release notes. The device path can exist even if the current process can’t open it or change system routes. In containers and managed sessions, the host environment also controls interface and routing permissions. If the logs report that interface creation failed, distinguish an unavailable device from insufficient permissions. If the interface is up but a destination still fails, check routing and DNS rather than granting the app broader permissions.

Configure launch at login only after a manual connection is stable. Starting an app with the desktop session is different from running a system service at boot: the former can use GUI settings in the right user session, while the latter may run before login, read different desktop proxy settings, and use a different user directory. To test launch at login, sign out and back in, then check the tray, active node, and logs. A background process alone doesn’t prove the system proxy is working. If it fails only when launched automatically, check network readiness and whether an old process is starting twice. See also Linux Package Installation and Autostart.

Android: Subscription Groups and VPN Routing

Quick reference
ItemOptionsRecommendation
Clientv2rayNG / v2flyNGv2rayNG recommended; choose an alternative for specific protocol needs
APK architecturearm64 / universalChoose an arm64-only build only after confirming system support
Routing methodAndroid VPN serviceCheck the authorized app on first launch

Choose a client, architecture, and installation source

Go to the Android downloads. v2rayNG, which uses the Xray core, is the recommended choice; consider v2flyNG only if you specifically need the V2Fly core. The two clients don’t support exactly the same node types and options. Before switching clients, check that your subscription’s protocol and transport requirements are supported. Importing a node doesn’t guarantee it can connect. Most recent Android phones can use the arm64 build, but if you’re unsure which app architectures your system supports, choose the universal package. A 64-bit processor doesn’t guarantee that the OS can install apps built for that architecture.

When you open the downloaded APK, Android may ask you to allow installations from the current source, such as your browser or file manager. Grant permission only to the source you’re actually using, and revoke it afterward if it was temporary. If device management policies prohibit this type of installation, check with your administrator first. If installation fails, distinguish an incompatible package from low storage or an existing app that can’t be upgraded. Don’t uninstall without a backup: subscriptions, manual nodes, and per-app settings may be removed.

Add a subscription, update the list, and start the service

In v2rayNG, open subscription group management, add a group, and enter the full subscription URL. Return to the list, update the subscription, confirm the results appear in the group, and select a node. If you have a QR code, check whether it contains a single-node link or a subscription URL, then use the matching import option in the client. Don’t use scanning services that upload the image. Keep manually imported nodes separate from subscription groups so an update doesn’t make it seem as though your selected node disappeared.

When you start a connection, Android shows a VPN connection request. Confirm that it comes from the client you selected before approving it. This permission lets the client receive traffic through the virtual network interface provided by the system; you don’t need to change Wi-Fi’s manual proxy settings. A VPN icon in the status bar means the service is running, not that the active node completed a handshake. First disable other network tools that may override the connection path, open a new browser page, and compare it with the client logs from the same time. To compare Wi-Fi and mobile data, switch only the network each time and keep the same node and test app.

Per-app routing, always-on VPN, and background disconnects

For per-app routing, first check whether the current mode allows only listed apps or excludes listed apps. The same browser in the list has opposite effects in these two modes. Test with one app before adding others. If the app is in a work profile or managed by device policy, a client in your personal profile may not be able to route its traffic. Don’t enable per-app routing, always-on VPN, and block connections without VPN all at once just to troubleshoot one app.

If the connection drops in the background or when the screen turns off, check notifications and client logs first. Did the service stop? Did the network switch from Wi-Fi to mobile data? Is the node still selected but new connections failing? Check the client’s battery restrictions and background activity settings only if the evidence points to a background limitation. If no apps can connect, check which VPN app the system is currently bound to and whether “Block connections without VPN” is on. Before changing anything, confirm whether you or your administrator configured these settings. When comparing v2rayNG with v2flyNG, run only one at a time so a system VPN switch isn’t mistaken for a dropped node.

System Proxy & TUN: Routing Scope and Verification

Quick reference
EndpointApplies toRecommendation
System proxyApps that read the system proxyPreferred for the first desktop connection test
Local SOCKSApps that support manual SOCKS configurationUse to diagnose a single app
TUNTraffic routed through a virtual interfaceCheck routes and DNS before expanding coverage

The system proxy selects the entry point; routing selects the exit

On desktop, the system proxy toggle typically points the OS proxy settings to a local listener. Apps have to read those settings to send requests to the client. A browser using the proxy doesn’t mean terminal commands, background updaters, or LAN apps use the same endpoint. The client’s routing settings apply to requests that have already reached it: based on domain, address, or other rules, the client can proxy, bypass, or block them. Changing the routing policy to global doesn’t make apps that ignore the system proxy send traffic to the client. Likewise, enabling TUN doesn’t mean every destination will use a remote node.

Isolate a local proxy test with a single request

If curl is installed on your desktop, you can bypass system proxy selection and test the local SOCKS address directly. The command uses a public reserved domain for illustration; in a real test, replace it with a known-accessible HTTPS destination. First confirm that the client provides a SOCKS endpoint and that the port matches the interface. Don’t enter an HTTP proxy port or a remote node’s port. In Windows PowerShell, use curl.exe to avoid invoking an alias with the same name. The example’s socks5h passes the destination hostname to the SOCKS service instead of resolving it locally in curl; it doesn’t guarantee that the client will use any particular DNS service afterward.

curl --noproxy "" --proxy socks5h://127.0.0.1:10808 --max-time 15 -I https://example.com/

If the request clearly reports that the local connection was refused, check the listening port and process status first. If it reaches the local service but times out waiting for the destination, check the routing and remote connection details in the logs. An HTTP response from the destination means this request received an application-layer response; it doesn’t prove that other destinations, apps, or UDP traffic work. If the destination doesn’t accept HEAD requests, retest with a regular GET request. After testing, don’t change the local listener to accept LAN connections. A loopback address is enough for a test from the same machine; exposing the listener to other devices changes who can access it.

Verify routing and DNS after enabling TUN

TUN uses a virtual network interface to receive traffic routed to it by the OS. First test the same app with the system proxy disabled, then enable TUN separately. Check three things: the app whose traffic should be routed, local services that should remain direct, and a test destination accessed by domain name. If LAN resources fail only while TUN is on, check the LAN subnet and selected interface first. If the domain fails while the network is reachable, check how DNS requests are routed. Don’t use a bare IP address as the final HTTPS test: certificates, virtual hosts, and routing rules may depend on the domain name.

On supported cores and with a compatible configuration, FakeDNS can return a virtual address for a domain and use a mapping to recover the original domain when the connection reaches the client. This requires DNS queries and connections to follow compatible paths. Results can differ if an app resolves names itself, caches them across a mode change, or sends the virtual address through an unexpected interface. Most installations don’t need this feature enabled. Consider it only when you have a specific need to route traffic by domain; note the behavior with it disabled, then change this setting alone. For details, see How FakeDNS Maps Virtual IP Addresses; for terminology, see the Glossary.

Common Setup Issues: Troubleshoot by Failure Stage

Quick reference
SymptomCheck firstNext step
Empty listSubscription update resultCheck the group and the type of response
Local connection refusedClient listenerCheck the port, process, and startup errors
Only some apps failWhether traffic reaches the clientCompare system proxy, TUN, and per-app settings

Gather evidence: record one reproducible test

Summarize the issue in a testable sentence—for example, “The same browser opens the test page with the system proxy off, but the local listener reports an error when it’s on”—rather than just saying you can’t connect. Record the network, proxy mode, active group, and test target, then capture only the logs covering that request. Redact subscription query parameters, account identifiers, and node addresses before sharing logs. When testing again, don’t change networks, nodes, and cores all at once. Otherwise, even if the issue goes away, you won’t know which change helped.

Check the first error related to the failure, not just the last log line. Configuration parsing, port binding, and remote handshakes happen at different stages. If an earlier stage fails, later timeouts may just be a consequence. A single latency test doesn’t guarantee that real traffic works: it may only test the server port or use a different destination. Assess the latency result alongside the test type, log timestamps, and actual app behavior. For a complete near-to-far troubleshooting sequence, see Troubleshooting Node Timeouts and Connection Failures.

Common symptoms and what to check next

Subscription added, but no nodes appear?

Saving a group stores the URL; it doesn’t fetch its contents. Manually update the group and check the logs for connection failures, access denied errors, or a format error. If the response is a login prompt or a regular web page, the client may not be able to parse it into nodes. Get a subscription URL the client supports from your provider account. If the update succeeds but the list is empty, make sure you’re viewing the group you just updated and that search filtering is off. If the old list still works, don’t delete it until you’ve confirmed the new subscription imports successfully.

Nodes appear in the list, but none can connect?

First check that the system date and time zone are correct and synchronized. Then confirm that an active node is selected, the core is running, and the local proxy port is listening. Send a request to your fixed test target. If no corresponding entry appears in the logs, check the app’s proxy endpoint first. If the request reaches the client, distinguish name resolution, remote connection, and transport handshake failures. Change the transport type, service name, or TLS settings only when you have the provider’s required values. Don’t disable certificate verification to get rid of an error; instead, check the time, destination name, and original node settings.

Did the issue start after switching nodes or upgrading?

Compare using the same old node first. If only updated entries fail, check whether the active group changed, the provider changed the port or transport, or the core supports the configuration. If all nodes fail after an upgrade, check whether you opened a different app copy, whether it’s using the original data directory, and whether an old process is still holding the port. Before restoring a backup, exit the client and confirm the data format is compatible. Don’t mix all configuration files from different editions.

Can’t connect after closing the window? How to restore access

First check whether the client is still running in the tray. Closing the window, stopping the core, and fully exiting are different actions. If you can reopen the client, disable any routing mode you enabled, then check whether the system proxy still points to a local port. If the client exited unexpectedly, restore the proxy, automatic configuration script, or VPN settings you recorded before setup. On devices with a corporate proxy, don’t delete every proxy setting. Once access is restored, repeat the test to the same destination and confirm that local network resources work too.