v2rayN Setup Guide for All Platforms

Before You Begin: Installers and Subscription Details

Understand the client, core, and server

v2rayN is a desktop GUI client for managing servers, subscription groups, proxy modes, and routing rules. Connections are established by the proxy core that the client launches. Use v2rayN on Windows, macOS, and Linux; on Android, v2rayNG with the Xray core is the primary option, while v2flyNG with the V2Fly core is an alternative. A GUI client does not provide the service: installing it will not create a working server or grant access to a subscription. Before setup, get a valid subscription URL or a share link containing all required connection details from your service provider.

A subscription is an updatable set of configurations, not a website username and password. Check that the service is still active, whether traffic limits apply, and whether there are restrictions on the number of simultaneous devices. A server address and port alone are rarely enough to restore a configuration; you may also need a user ID, transport type, TLS settings, or service name. Don't fill in missing fields based on scattered online examples. An invalid combination may save successfully in the client but fail during the remote handshake. Subscription URLs contain access credentials: copy the entire URL and obscure all of it in screenshots.

Check your system architecture and keep a recovery path

Choose an option on the download page for your operating system, then confirm your processor architecture. Windows offers x64 desktop and classic WPF editions; macOS packages are available for Apple Silicon and Intel; Linux packages vary by format (deb or rpm) and architecture (x64 or arm64); Android offers arm64 and universal builds. A successful download doesn't guarantee that the file will run on your device. Check the installer notes for OS and runtime requirements. For older systems, confirm compatibility before installing; matching client names alone don't guarantee that an upgrade will work.

Before setup, note whether you already use another proxy, VPN, custom DNS, or browser proxy extension. Multiple traffic-routing tools can cause unexpected routing or loops. During troubleshooting, keep to one clear proxy path at a time. If a client is already installed, export the settings you need and note the existing local port, subscription groups, and custom routes. Backups may also contain credentials, so store them in a controlled local folder. Upgrade separately from switching interface versions; keeping a recoverable configuration makes issues easier to isolate than repeatedly overwriting it.

Follow a minimal validation sequence

Start the client without enabling TUN and confirm the core starts. Import a subscription, update the server list, and select an active configuration. Then enable the system proxy and test a site in a browser that honors system proxy settings. Add TUN, custom DNS, or complex routing only after this basic path works. This sequence separates installation, subscription, and traffic-routing issues, making it easier to identify what changed when you test each step.

System time is part of the setup too. An incorrect date, time zone, or clock sync can cause certificate checks and some protocol authentication to fail. For testing, choose one site you can normally access directly as a baseline and another that should use the proxy; record what happens with each. A successful speed test only confirms that the path to its test destination works, not that every site and app is routed through the proxy. Check core logs, actual page loads, and exit IP details during follow-up tests; don't rely only on the tray icon or connection button color.

Windows: Install and Set Up v2rayN

Install the preferred edition and confirm the core starts

Choose v2rayN from the Windows downloads. The desktop edition uses a cross-platform interface, while the WPF edition has the classic Windows interface; menus and configuration folders may differ. For a first install, the desktop edition is a good starting point. If you're used to WPF, you can keep using that edition. Follow the installer prompts. If you downloaded a package that needs extraction, extract all files to a permanent folder before launching the app. Don't run it from the archive preview or copy only the main executable and leave its dependencies behind.

You usually don't need to run the client as an administrator for the standard system proxy. If a first launch reports a missing runtime, install the component it specifies; don't mistake a missing dependency for an unavailable server. Open the logs and check that the client-launched core doesn't exit immediately. If startup fails, check security software alerts, write permissions for the app folder, and any leftover process with the same name. Don't disable all system protection as a troubleshooting step; investigate the specific file source and error instead. Keep the app out of temporary download folders, where cleanup could remove dependencies or configuration files.

Subscription groups, servers, and system proxy

Open subscription group settings, create a group named for its source, paste the full subscription URL into the address field, and save. Return to the main window and update the subscription. If the client offers multiple update methods, try updating without the current proxy first; otherwise, the client may need a connection it hasn't established yet to fetch its own configuration. After the update, confirm the servers appear in the expected group and select one as the active configuration. Highlighting a row may not activate it: use the current interface's Set as Active Server action and confirm the status changes.

Run a real connection test and review the failure reason instead of relying on the list order. After selecting a working server, set the system proxy to “Set system proxy automatically” and test with a regular browser. To keep the initial setup simple, you can start with an existing “Bypass mainland China” preset. For a clear comparison, temporarily switch to a global proxy rule and test the same destination, but remember that system proxy and routing are separate layers. The system proxy determines which apps send requests to the local proxy; routing determines which exit the core uses for requests it receives. Browser proxy extensions can override system settings, so pause them during testing.

TUN permissions and Windows-specific issues

Consider TUN mode only after the system proxy works and you need to route traffic from an app that ignores system proxy settings. Follow the client's prompts to grant administrator permission, install required components, or start the necessary service, then check the virtual adapter and core logs. A permission prompt doesn't mean you can ignore startup errors: the client window may open even if TUN failed to initialize. If adapter creation fails or permissions are insufficient, close leftover processes and return to a standard system proxy test. Don't repeatedly reinstall network components or delete physical adapters or system routes without a clear reason.

If a local port is already in use, the core will often report a listener error. Check the actual port in the client settings, then identify the process using it and confirm whether it's another client instance. If you change the port, update any apps configured to use it manually; otherwise, they'll keep trying the old port. If the connection drops after waking from sleep or switching between wired and wireless networks, disable TUN and reconnect. Check that the network itself is back before troubleshooting the proxy. Enable startup on boot only after manual connections are stable, and make sure two interface editions aren't both taking over the proxy after sign-in.

Before exiting normally, disable TUN and use “Clear system proxy” to restore your regular network settings. After an unexpected shutdown, if no websites load, check whether Windows proxy settings still point to a local port with no listener. Clear only the leftover proxy; don't reset all network settings. If your device is managed by an organization, don't override its required proxy. For a fuller first-install walkthrough, see First-Time v2rayN Installation and Setup. For troubleshooting, refer to its checks for installation folders and startup.

macOS: Choose the Right Build, Manage Permissions, and Restore Proxy Settings

Choose the installer for your processor

First, check the processor in About This Mac. Choose the Apple Silicon build for a device with an Apple chip, or the Intel build for an Intel processor. See the macOS downloads. Open the downloaded disk image and move the app to the Applications folder as prompted, then launch it from there. Don't run it long-term from a temporarily mounted image; after ejecting the image, login items or shortcuts may point to a location that no longer exists. Finish installation before handling first-launch prompts so installation, updates, and permission changes don't overlap.

If macOS displays a security alert, first confirm the installer came from the selected download page, then follow the specific instructions under Privacy & Security. Don't disable system-wide security to launch an app, and avoid running Terminal commands from unknown sources to bypass restrictions. An incompatible processor architecture, an unsupported OS version, and a damaged app are different issues and should be checked separately. Once the window opens, confirm that the core can start too; a working GUI doesn't mean the core process or TUN components have the permissions they need.

Import a subscription and test the system proxy

Create a subscription group in v2rayN, enter a name and the complete subscription URL, save it, and update the subscription. If the update fails, check the network and URL without enabling TUN first. Don't paste a subscription URL into a regular server address field. After a successful update, select an active server, run a real connection test, and then enable automatic system proxy configuration. When testing in a browser, make sure it doesn't have separate proxy settings or an extension routing requests. Use the same destination before and after switching networks to avoid mistaking a change in test site for a change in client status.

On macOS, proxy settings are usually tied to a specific network service. Wired, wireless, and other network interfaces may have separate settings. After switching interfaces, check that the active service still points to the expected local port. Work devices may also have configuration profiles or management policies; identify where a restriction comes from if the client can't change the settings. The system proxy affects apps that honor it, but terminal tools and some apps use their own connection settings. A working browser doesn't prove that every command-line tool follows the same proxy path.

TUN, waking from sleep, and quitting the client

If you need broader traffic coverage, configure TUN permissions or its helper service as prompted by the interface. Permission steps vary by package, so follow the current app's instructions rather than copying administrator steps from another platform. After enabling TUN, check that the core keeps running and look for errors involving routes, device access, or DNS. If another VPN is controlling the default route or DNS, disconnect it before testing. Avoid stacking multiple tools and repeatedly switching the default route; this makes it difficult to match client logs to the actual traffic path.

After waking from sleep, the network interface, gateway, and DNS may have changed. Confirm that the direct connection works, then reconnect the proxy. If only TUN fails while the system proxy still works, focus on virtual interface and route recovery rather than immediately importing the subscription again. On public Wi-Fi that requires a sign-in page, disable traffic interception until network authentication is complete, then reconnect the proxy. A sign-in page that won't load doesn't necessarily mean the server is down; the local network may not yet allow internet access. Switching servers repeatedly won't fix that.

Closing the window may not quit the client. Check the menu bar and background processes. To restore normal network access, disable TUN first, then clear the system proxy set by the client. If the app exited unexpectedly, open the proxy settings for the active network service and check for a leftover local proxy address. Remove only entries added by this client; keep existing organization settings. Add a login item only after the connection workflow is stable. If an older process remains after an update, quit it before opening the newly installed app to avoid two processes listening on the same port.

Linux: Packages, Desktop Environments, and Permissions

Choose the package format and architecture for your distribution

Choose v2rayN from the Linux downloads. Use deb packages for distributions that use the corresponding package system, and rpm packages for distributions that use theirs. Check x64 versus arm64 as well; matching file extensions alone don't guarantee compatibility. Run the command below in a terminal to check the machine architecture and system details: x86_64 commonly maps to x64, and aarch64 to arm64. The distribution and processor are separate details; for containers, compatibility layers, or remote sessions, check the actual runtime environment too.

uname -m
cat /etc/os-release

Use your distribution's software installer or package manager to install the local package, so it can handle dependencies. If it reports a missing graphical runtime, check the specific dependency instead of forcing installation past the error. If installation succeeds but the window won't open, launch the installed app from a terminal and review the output. Distinguish display environment and runtime issues from core startup problems. Don't run the entire GUI client in a superuser session long-term; this can create configuration files with inconsistent ownership and increase the impact of future actions.

Importing subscriptions and desktop proxy differences

Open v2rayN, import a subscription, update the server list, select an active configuration, and confirm that the core can listen on a local port before setting a proxy. System proxy support differs across Linux desktop environments: some have a unified network proxy panel, while some apps use their own settings or environment variables. So even if “Set system proxy automatically” succeeds, not every desktop app will necessarily honor it. Test first with a browser that explicitly supports the selected proxy type, then check proxy settings in apps that aren't working. Avoid routing all system traffic until you know you need to.

Command-line HTTP tools can use an explicitly specified proxy to help distinguish proxy-path issues from desktop settings. The command below applies only if the client settings confirm that the HTTP or mixed listener uses port 10808. If the actual port differs, update the command before running it. This sends the request for the example site through the local proxy; it doesn't change the system proxy or route traffic from other apps. Check the response status, connection errors, and matching client logs. Don't assume the proxy is working just because the command finished.

curl --proxy http://127.0.0.1:10808 --head https://example.com

If you've set proxy environment variables in the terminal, note their scope during testing. Variables in one terminal session may not reach an already-open GUI app, and GUI settings may not apply to terminal tools. If those variables remain after quitting the client, commands may keep trying to connect to a stopped local port. Compare results with an explicit proxy test before changing the current session settings. Don't add proxy variables of unknown origin to global startup files just to make one command work.

TUN, DNS management, and permission boundaries

TUN on Linux relies on a virtual network device, permission to manage routes, and the client's current startup method. Follow the permission steps in the client documentation or interface, then check the logs for a missing device, insufficient permissions, or a route conflict. Don't grant broad permissions to every program or change executable permissions without understanding the impact. Containers, restricted desktop sessions, and remote environments may not have access to a virtual device or network management permissions. In those cases, fall back to app-level proxy settings instead of repeatedly restarting the GUI.

DNS may also be controlled by a network manager, a system resolver, or manually edited files. If domains fail after enabling TUN but existing connections still work, check the client's DNS settings and the system resolution path first, then look for another service overriding them. Don't clear system resolver settings indiscriminately; network services may regenerate them on reconnect. After disabling TUN, confirm that the default route and DNS settings have been restored. Checking the regular network with the client closed can help distinguish a remote issue from leftover local settings.

Before enabling startup at boot or login, confirm that the graphical session, key store, and network are ready. Login startup and a background service are different run modes; don't enable both unless that's an intentional setup. If a regular user can't write configuration after an upgrade, check whether running with elevated permissions changed folder ownership. Back up first, and limit any repair to the directories the client actually uses. If the logs show a working local listener but the browser fails, check the desktop proxy settings before replacing server details.

Android: v2rayNG and VPN Connection Management

Install the client and authorize the connection

For Android, v2rayNG with the Xray core is the recommended option. If you need the V2Fly core, use v2flyNG. These are separate apps; don't expect them to share subscriptions, active servers, or VPN status. Choose a package from the Android downloads. For most recent devices, check arm64 first; if you're unsure of the architecture or arm64 won't install, check system information and choose the universal build. A universal build supports a wider range of devices but may still require a particular OS version. Before updating an installed app, save your subscription details and any settings you need.

When installing, grant permission for this file source if Android prompts you, then revoke that source permission later if you don't need it. If Android says the app wasn't installed, check the architecture, available storage, OS compatibility, and installation source before taking other steps. On the first connection, Android asks for VPN permission. This authorizes the client to route traffic through the system's network interface. After granting permission, check the app status and logs too; dismissing the system prompt doesn't mean a remote server connection succeeded.

Import a subscription, choose a server, and test the connection

Open subscription group settings, add a group, paste the full URL, save, and select Update Subscription from the menu. If you import a share link from the clipboard, it may add one or more configurations without creating an automatically updatable subscription. Keep these methods distinct in your notes; otherwise, you may expect a manually imported server to update later when it won't. After a subscription update succeeds, confirm the expected configurations appear and select an active server. Without one, tapping Connect can't establish a valid remote connection.

Run a real connection test first, choose a server that passes, then tap Connect and confirm the status changes. Test a target site in a browser and check exit IP details and logs if needed. If the test succeeds but an app doesn't use the proxy, check whether app-level routing is enabled. Proxy only selected apps and exclude selected apps mean opposite things. Selecting an app in a list doesn't always mean it will be proxied; check the current mode. After changing the app list or routing rules, reconnect the VPN as prompted so the new settings take effect.

Background restrictions, network changes, and core differences

Android usually allows only one active VPN connection per user profile. Another VPN, some VPN-based filtering tools, or a work profile may conflict with the client. If it disconnects immediately after connecting, check whether another tool is automatically reconnecting. Review both app-level routing and the system VPN's coverage; changing core routing alone won't put every app through the proxy. Don't apply desktop system-proxy assumptions to Android. A common connection method here is for the client to route traffic through a local entry point using Android's VPN service.

If the connection drops when the screen turns off but returns as soon as you reopen the app, check battery optimization and background activity restrictions. Allow the background activity the client needs in the device settings, then see whether the connection stays stable. Don't grant every app unrestricted permissions. Persistent notifications show the connection status; hiding one doesn't necessarily keep the service running. After switching between Wi-Fi and mobile data, the connection may need to be re-established, especially if the network requires a sign-in page, mobile data isn't available yet, or the device is in power-saving mode. Confirm the direct connection first, then reconnect the client so a network change isn't mistaken for an expired subscription.

v2rayNG and v2flyNG use different core families. Whether a configuration works depends on the core's support for its protocol, transport, and fields—not just whether the share link can be imported. When switching clients, import the subscription again and test independently. Don't copy all internal files from one app to the other. Follow the service provider's requirements if it specifies a particular core capability. If you don't have a specific compatibility need, stabilize one client configuration before trying the alternative; switching between apps can make connection status confusing.

System Proxy and TUN: Traffic Coverage and Local Ports

Understand the traffic entry point and routing exit separately

A system proxy tells apps that honor the system settings to send requests to a local HTTP or SOCKS proxy. It doesn't force all traffic through the proxy. TUN uses a virtual network interface and routes to pass packets on the relevant path to the proxy core. It usually covers more traffic, but is still subject to routing, app exclusions, and system restrictions. A global proxy rule only chooses an exit for traffic inside the core; it doesn't mean every app is sending traffic to the core. First check whether a request reaches the client, then decide whether it should go direct or through the proxy. This keeps issues in the two layers separate.

“Set system proxy automatically” usually writes the current local proxy entry; “Clear system proxy” removes the related settings; and “Don't change system proxy” leaves the current system settings alone. The last option doesn't stop the core or restore settings changed earlier. During troubleshooting, check whether the client is still listening, whether the system still points to that port, and whether the app honors system proxy settings. After an unexpected exit, the system proxy may remain configured. A browser then tries to connect to a port with no listener, making every site appear unavailable.

Local listeners, LAN access, and overlapping modes

Local HTTP, SOCKS, or mixed ports are entry points for apps to connect to the client, not remote server ports. A mixed port can usually accept multiple proxy request types supported by the core, but check the settings documentation for the protocols it handles. Keep the current default listener for initial setup. If the logs report that the address is in use, identify the conflicting process or choose an available port. Don't substitute a listener address, server address, or subscription URL for one another. A listener bound to the loopback address is mainly for local access; another device cannot reach this computer using its own loopback address.

“Allow connections from LAN” expands who can access the proxy. Enable it only when you specifically need to share the proxy. You'll also need to consider the listener address, firewall, and proxy authentication; don't leave the port exposed just because the local network is trusted. To connect another device, use the computer's LAN address and actual listener port, and restrict access to the appropriate network. For a single-device setup, local-only access is easier to manage. During troubleshooting, don't open LAN access, change the port, and enable TUN all at once; you'll lose track of which change affected the result.

How to enable TUN and roll back safely

Before enabling TUN, save a working system proxy configuration and confirm the remote connection works. Then follow the platform's steps for permissions, components, or services. After enabling it, check that the core keeps running and that routes and DNS are set up as expected. If the network stops working altogether, disable TUN, clear any leftover system proxy, and test the direct connection. Once that works, return to the known-good system proxy path. Don't keep changing server transport settings while troubleshooting TUN; that removes a working baseline for comparison.

These modes aren't mutually exclusive in every implementation, but use a single path when troubleshooting for the first time. In some environments, an app's connection to the local proxy may itself be captured by TUN. Incorrect exclusions or loopback handling can cause loops or duplicate processing. Use the client presets and don't force the proxy server address back through the same proxy exit. If UDP apps, games, or real-time communications fail, check separately whether their traffic reaches the core, whether the remote server supports forwarding it, and whether the current network allows it. A browser test alone can't verify all of these.

After setup, test the full connection cycle: the target is reachable while connected, direct access returns after stopping, and a restart doesn't report port or route conflicts. Enable auto-connect or leave the client running in the background only after all three steps are stable. Save the original values before changing system network settings, and don't override restrictions on managed devices. Choose a mode to meet a specific app's needs; broader traffic coverage isn't automatically better.

Routing and DNS: Rule Order and Split-Tunnel Testing

Start with a preset and understand rule order

Split tunneling uses domains, destination IPs, ports, and other conditions to choose an exit for traffic that has already reached the proxy core. Start with a client preset and confirm normal access works before adding custom rules one by one. A common “Bypass mainland China” preset uses rule resources to separate direct and proxied traffic, but its behavior depends on the current core and rule files. “Global” should also be understood as the exit policy in the client's corresponding preset, not as routing every app at the operating-system level. Before configuring rules, identify which services should connect directly and which should use the proxy.

Rules are usually evaluated in order, and the first match determines what happens. Put more specific exceptions before broader rules. A broad direct rule may prevent a later, precise proxy rule from ever matching. Add one rule at a time and record the test domain, expected exit, and actual logs. Don't combine rule snippets from different cores; similar field names don't guarantee compatible resource formats, tag names, or defaults. A GUI routing editor and the core's raw configuration are different layers, so use the import method supported by the interface.

How domain, IP, and rule resources work together

Domain rules are suited to matching sites or services; IP rules are suited to specific networks and resolved addresses. Some connections reach the core with only an IP address, so domain matching may depend on how the app makes the request, the DNS path, and sniffing settings. For geosite and geoip rules, make sure the required rule resources are present and compatible with the core. A missing resource or incorrect tag may prevent startup or cause unexpected matches. Don't treat rule resource updates as subscription updates: they update different data. Check them separately when troubleshooting.

This Xray/V2Ray-style routing snippet demonstrates direct routing for an exact domain suffix and private IPv4 ranges. It isn't a complete connection configuration. The existing configuration must define a direct outbound tagged direct; without it, the snippet can't be used as written. It doesn't define a proxy server or determine the default route for unmatched traffic. If the GUI accepts rules one at a time, enter each field separately. Don't paste the whole object into a domain field or overwrite the complete configuration generated by the client.

{
  "routing": {
    "domainStrategy": "AsIs",
    "rules": [
      {
        "type": "field",
        "domain": ["domain:example.com"],
        "outboundTag": "direct"
      },
      {
        "type": "field",
        "ip": ["10.0.0.0/8", "172.16.0.0/12", "192.168.0.0/16"],
        "outboundTag": "direct"
      }
    ]
  }
}

Troubleshoot DNS and routing separately

DNS converts domain names into addresses, but the path used for resolution may differ from the exit used for the website connection. System DNS, the client's built-in DNS, and browser DNS-over-HTTPS may all be involved. If the browser uses its own resolver, the domain information in client logs may not match system lookup results. Identify which component is resolving the name before changing anything; don't modify the system resolver, browser settings, and core DNS at the same time. Testing with a static IP can help narrow things down, but it doesn't replace a normal domain test because TLS and virtual hosting may still require the correct hostname.

If only a few sites fail while most work, check whether those sites use the wrong exit, match an unexpected rule, or resolve to an unexpected address. If the issue started after a routing change, restore the previous working rules to test before changing subscriptions. Check IPv6 as well: if the system prefers an IPv6 address but the current traffic capture or remote path doesn't support it, connections may be unstable. Configure dual-stack routing to match your network's actual capabilities. Don't blame all IPv6 traffic without evidence.

When testing rules, start a new connection rather than refreshing a page that has been open for a long time. Browser caches, reused connections, and app caches may keep using the old exit temporarily. If needed, close and reopen the app, then check the rule match in the core logs. For more on rule structure, see Domain, IP, and Split-Tunneling Rules in Practice. If you use multiple subscriptions, organize them into groups first; see Managing Multiple Subscription Groups. This helps avoid confusing server filters with traffic-routing rules.

Common Setup Questions: Restore Connections by Troubleshooting Each Layer

Find the layer where the connection fails

Troubleshoot from the local end outward: can the app open, does the core keep running, is the local port listening, does the app send requests to the client, can it connect to the remote server, and finally, are routing and DNS working? Keep a clear result for each step; this is more useful than reinstalling the app and changing subscriptions at the same time. Note error types and timestamps from the logs. Before sharing logs, remove subscription URLs, user IDs, and other credentials. Increase log verbosity only as needed during diagnosis, then restore the normal level to avoid keeping unnecessary connection records.

If every server fails at once, check shared factors first: the local network, system time, core startup, subscription validity, and proxy mode. If only one server fails, check that configuration's address, port, transport, and TLS settings. Updating a subscription may fix a change made by the service provider, but it won't resolve a local port conflict or missing permissions. For a detailed, layer-by-layer checklist, read How to Troubleshoot Node Timeouts and Connection Failures. For short answers, visit the FAQ.

Subscriptions, Connection Tests, and Browser Access

Restoring the network, updates, and configuration backups

Before upgrading, note how the client was installed, where its configuration is stored, and which interface version you're using. Export subscription groups and custom routing rules, then keep the backup somewhere secure. Backups may contain server credentials and shouldn't be posted publicly. After upgrading, test the old minimal working setup before reviewing new settings. If configuration migration fails, don't repeatedly save from multiple versions in the same folder. If you need to rebuild the configuration, restore servers from the complete subscription first, then migrate custom routes and app rules one at a time to avoid carrying over a broken state.

After restoring the setup, test three steps: connect, stop, and connect again. Record the final mode and port so you can return to a known working state if the same issue comes up again, rather than changing every setting from scratch. If you're new to the client, follow the steps in the Quick Start Guide. If you already know your platform and architecture, go straight to the download page and choose the appropriate client. This guide explains the limits of each setting; use the menus and permission prompts shown in your current client and operating system as the source of truth.