V2Ray Setup for Every Platform

Before You Start: Clients, Cores, and Subscriptions

First, understand the three components. The client provides the interface, stores subscriptions, lets you select nodes, and manages proxy settings. The core parses connection parameters, establishes transports, and applies routing. A subscription is a source of configuration, not a client. Installing the software only means it is ready to run; you still need a valid node configuration to connect. This site provides client selection and setup guidance, but does not offer subscriptions or manage account status, traffic limits, or server settings on behalf of providers.

How Clients and Cores Fit Together

For desktop platforms, v2rayN is the recommended choice for Windows, macOS, and Linux. On Android, v2rayNG with the Xray core is a good default; consider v2flyNG if you need a V2Fly core configuration. Project V is the starting point for this technology ecosystem. V2Fly continues V2Ray’s maintenance and development, while Xray is another actively evolving core. Similar client interfaces do not guarantee identical core implementations or parameter support. If a protocol is unsupported or a transport is unrecognized, check the configuration requirements first, then consider switching cores. Don’t judge compatibility by name alone.

Before downloading, check your operating system, processor architecture, and package format. x64 is for common Intel and AMD desktop processors; arm64 is for compatible ARM devices. These are different builds, not the same package in different sizes. Desktop and Android installers are not interchangeable either. Choose your platform on the client downloads page. Back up existing client data before installing so you don’t change the client, core, and subscription all at once while troubleshooting.

Subscription Links and Configuration Details

Have the full subscription URL ready. When copying it, leave out explanatory text, line breaks, and trailing punctuation. A subscription URL may contain an access token, making it similar to an account credential; don’t share it in public chats, screenshots, or logs. QR codes may also contain full node details. When asking for help, share the error type and protocol name, but redact the subscription URL, user ID, password, and server details. A successful import does not mean the configuration is still valid; check the service period, traffic allowance, and node status too.

For the initial setup, disable other proxies or VPNs, check that the system clock is correct, and make sure your regular internet connection works. Sign in first to any corporate or campus network, or hotel captive portal; a proxy client cannot complete these steps for you. Note your current system proxy and DNS settings, then change one thing at a time. On managed devices, policies may restrict certificates, virtual network adapters, and network permissions. Check what’s allowed rather than repeatedly trying to bypass restrictions by escalating privileges.

VMess, VLESS, and REALITY: What Each One Does

VMess and VLESS are connection protocols. TLS and REALITY are related security handshake settings, while TCP and WebSocket describe transport methods. These fields must work together; a protocol name alone is not a complete connection setup. VMess is sensitive to device clock errors. VLESS does not provide encryption by itself, so use the security mechanism specified by your configuration. REALITY is not a universal speed-boost switch that you can apply to any node. Your client must support it, and you must enter the public key, server name, and other parameters supplied by the server.

Windows: Install v2rayN and Configure the System Proxy

Choose v2rayN from the Windows downloads. The desktop edition uses a cross-platform interface; the classic WPF edition keeps the familiar Windows workflow. These are differences in interface and implementation, not node quality. If you’re new, start with the desktop edition. If your current setup works well, there’s no need to switch interfaces just to troubleshoot a connection. Install the app according to the package instructions. Follow any runtime requirements shown by the installer rather than preinstalling a list of unrelated components from an old guide.

Installation, Startup, and Data Locations

After launching, make sure the main window opens normally, then check the logs for core startup errors. If you downloaded a portable archive, extract it fully to a writable folder; don’t run the app from the archive preview. The installation folder, user data folder, and temporary folder may be separate. Use the client’s export or backup feature rather than copying only the desktop shortcut. If you see a security warning, check the download source and the system’s explanation. Permanently disabling system protection is not a recommended fix for startup problems.

You usually don’t need administrator privileges for the system proxy. Creating a virtual network interface for TUN may require additional permissions. Set up the subscription and connect to a node with standard permissions first; handle TUN separately once the basic connection works. If you get a permissions error at every launch, identify what failed: writing to a folder, binding a port, and creating a virtual adapter are different issues. Running the entire app with elevated privileges is not always the right fix.

Add a Subscription and Select the Active Configuration

Open subscription group management, add a group, and enter the subscription URL. Give the group a recognizable name. Save it, then select “Update subscription (via proxy disabled).” This is usually easier to troubleshoot before you have a working proxy. If the subscription provider requires proxy access, connect to a working node first, then choose “Update subscription (via proxy enabled).” Check the update log for results and confirm that nodes appear in the main list. Saving the URL without running an update is a common reason for an empty list.

Select the node you want to use and set it as the active configuration, then check that the core is running. Don’t run the desktop and WPF editions at the same time against the same local listening port; the second process may fail because the address is already in use. Duplicate node names across subscription groups are common. Check which group is selected so you don’t keep using an outdated node from an old group after updating a new subscription.

System Proxy, TUN, and Restoring Your Network on Exit

In the tray menu under “System proxy,” select “Set system proxy” so apps that read the Windows system proxy can connect through the local listener. “Clear system proxy” removes the system proxy settings. “Do not change system proxy” leaves the current settings alone; it does not clear them. Browsers may also be affected by extensions, company policies, or their own network settings, while some command-line tools don’t use the system proxy at all. A correct tray status is only one condition for routing traffic; verify each app separately.

Consider “Enable Tun” when you need to route apps that don’t read the system proxy. Before enabling it, close other VPNs and make sure the rules won’t send your local gateway, LAN services, or the client’s own connection into the tunnel by mistake. Before exiting, turn off TUN, clear the system proxy, and then quit the client normally. If your browser can’t connect after the app closes unexpectedly, check Settings → Network & Internet → Proxy in Windows. The manual proxy may still point to a local port that is no longer listening.

macOS: Choose the Right Chip, Grant Network Access, and Restore Proxy Settings

Before opening the macOS downloads, go to Apple menu → About This Mac. Choose arm64 for Apple silicon and x64 for an Intel processor. Architecture determines whether the app can run natively; it doesn’t change your subscription. Don’t guess the chip based on when the device was purchased. Download the matching v2rayN disk image, then move the app to Applications as instructed by the package. Avoid running it long-term from a mounted disk image or your Downloads folder.

First Launch and System Permissions

The first launch may trigger a macOS security prompt. Check the app’s source, then follow the confirmation steps shown by macOS. You can review prompts related to the app under System Settings → Privacy & Security. The exact prompt depends on your macOS version, signing status, and management policies, so don’t expect every device to show the same buttons. If macOS reports that the app is damaged, built for a different architecture, or restricted by an organization’s policy, read the reason first. Don’t run an unverified Terminal command to change security settings across the whole system.

Once the main window opens, check that the client can save settings and start the core before setting up network access. Changing the system proxy and creating a virtual interface are separate operations; permission for one doesn’t mean the other is ready. If the client requires an additional component or administrator approval, follow the workflow it provides. Company-managed devices may prohibit tunnel interfaces, and repeatedly reinstalling a regular app won’t remove that restriction.

Import a Subscription and Check the Active Node

Add and save the subscription URL under “Subscription groups,” then run the relevant update. To start, try “Update subscription (via proxy disabled)” to see whether your regular connection can reach the subscription provider. If the response is an account login page, verification page, or error message, the client may receive a response but fail to parse it into nodes. Check your subscription status on the provider’s account page rather than copying the returned web page text as node configuration.

After the update, select a node as the active configuration and check the logs for core parameter errors. For the first test, don’t change the transport, fingerprint, and security settings at the same time; the subscription usually includes the combination required by the server. An incorrect system clock can cause certificate validity or protocol authentication checks to fail. Check that the date and time are set automatically before disabling verification. If you need to make manual changes, copy the configuration first so a later subscription update doesn’t overwrite your troubleshooting notes.

Choosing Between System Proxy and TUN

With “Set system proxy” enabled, apps that read the system proxy will usually use the client. In System Settings → Network, select the active network service and open its details to review proxy settings. Depending on your macOS version, these options may be under Details or Advanced. Wi-Fi and Ethernet are separate network services, so check the settings again when you switch connections. If a browser works but a terminal app doesn’t, that doesn’t automatically mean the node is faulty; the terminal app may need its own proxy settings.

TUN is for cases that need broader traffic coverage, but it can also affect DNS, routing, and LAN access. First test a specific request using the system proxy, then enable TUN. That makes it easier to identify where a problem starts. Other VPNs, remote-work software, and network filtering tools may compete for routes. Use one traffic-capture method at a time. Once the connection works, restore other tools one by one; don’t let multiple apps change the default route at once.

If access fails after switching networks, waking from sleep, or connecting a new dock, first check whether the active network service changed, then check whether the client core is still running. Clear the system proxy and turn off TUN before quitting normally. If the client has stopped but traffic still points to a local proxy, restore the proxy settings for the active network service. Don’t clear managed DNS or automatic proxy addresses in bulk without recording their original values.

Linux: Package Formats, Desktop Proxy Settings, and TUN Permissions

On Linux, identify your distribution’s package format and then your processor architecture. Debian- and Ubuntu-based systems generally use deb packages; Fedora and other RPM-based distributions use rpm packages. Match x64 or arm64 to your device—a matching package format doesn’t guarantee a matching architecture. Choose v2rayN from the Linux downloads. Open the package with your system’s software installer so the package manager can handle dependencies and installation records, rather than copying files out of the app manually.

Check the Runtime After Installation

If the graphical installer reports missing dependencies, refresh your system repositories and check which components are missing. Library names, desktop environments, and display servers vary across distributions, so don’t copy dependency lists from another system. If the app doesn’t appear in the menu, try logging out and back into your desktop session. If startup fails, check the desktop launcher or system logs for the error. A missing window, a core that didn’t start, and a missing tray icon are three different symptoms.

Tray icons in GNOME and other desktop environments depend on desktop support. A missing icon doesn’t necessarily mean the process has exited; check the main window and process status before launching another instance. Don’t install untrusted desktop extensions just to show a tray icon. Back up client settings and any custom rules you maintain. When moving to another machine, recheck local paths, ports, and permissions rather than assuming the new system is identical to the old one.

Import a Subscription and Configure the Desktop System Proxy

Add and save a subscription under “Subscription groups,” run an update, and select an active configuration once nodes appear. Start the client as a regular user and check that the core can listen on a local port. If the logs report that an address is already in use, look for an old process or another proxy app. If you change the port, update every app that explicitly uses the old one too. Changing only the client port while leaving browser or terminal settings unchanged can lead to seemingly random connection failures.

Whether “Set system proxy” affects an app depends on the desktop environment and how the app reads proxy settings. GNOME, KDE, and standalone window managers may not use the same proxy configuration. Sandboxed apps may have additional restrictions. Check the actual proxy address in your desktop network settings, then test with a browser. If graphical apps work but your package manager doesn’t, check the package manager’s proxy settings before switching nodes.

# Check which proxy environment variables are set in the current terminal session
printenv | grep -iE '^(http|https|all|no)_proxy='

# Clear common proxy variables from the current terminal session only
unset http_proxy https_proxy all_proxy no_proxy
unset HTTP_PROXY HTTPS_PROXY ALL_PROXY NO_PROXY

The checks and cleanup above affect only the current shell; they don’t change desktop proxy settings, system services, or other running apps. If the variables come from a shell startup file, they’ll return in a new terminal until you remove them from the source. Apps vary in whether they support uppercase or lowercase variable names, so one variable being present doesn’t mean every app is using the proxy. Apps launched with elevated privileges may not inherit the regular user’s environment either.

TUN, Routing, and LAN Boundaries

TUN requires system support for virtual network interfaces and permission for the client to create an interface and configure routes as designed. Follow the current client’s permission prompts. Don’t run your entire desktop session as root or copy unverified commands that grant permissions. Before enabling TUN for the first time, close other VPNs and note the original default route and DNS settings. If the network stops working only after you enable TUN, check interface creation, permissions, routing, and DNS takeover logs.

Container networks, bridged virtual machines, and company VPNs can overlap with TUN routes. Keep a suitable direct route for LAN addresses, and bind local listeners to the loopback address by default. Only expose them to other interfaces when there’s a clear need, and use a firewall and authentication. If name resolution is still broken after exit, check the desktop network service and the DNS manager in use. Don’t change multiple resolver files at once; automatic network management may overwrite them the next time you connect.

Android: Choose a Client, Import a Subscription, and Route Traffic Through VPN

On Android, v2rayNG with the Xray core is the recommended choice. Use v2flyNG as an alternative when you need a V2Fly core configuration. Each app has its own data, permissions, and running state; installing the alternative won’t automatically transfer your subscription. Open the Android downloads. Most arm64 devices should use the matching package. Choose a universal package if you can’t confirm processor compatibility; it’s usually larger, not faster.

Allow Installation from This Source and Keep Your Settings During Updates

Android may ask you to allow your browser or file manager to install apps. Grant temporary permission only to the app you’re using for installation; turn it off afterward if needed. If installation fails, check whether the cause is an architecture mismatch, unmet system requirements, insufficient storage, or a signature conflict. Don’t uninstall immediately if an update fails, as this may also delete local settings. Back up using the client’s supported export method, and treat the backup file as sensitive data.

Apps installed from different distribution sources may have incompatible signing keys. A system conflict doesn’t mean your subscription is broken, and updating the subscription won’t fix an installation issue. If your current app works, keep it as is while you read the installation prompt and decide whether to migrate. After updating, check that your subscription groups, active configuration, and routing options are still as expected; the app icon remaining on your home screen proves nothing about the setup.

Subscription Groups, Clipboard Import, and QR Codes

Open subscription settings or group management, add a name and the full URL, save it, then run an update from the menu. The app may separate subscription management from the server list; after adding a group, return to the list and select it. Clipboard import works well for complete node links, while scanning a QR code is convenient for a single configuration. A QR code may also contain a subscription URL. After importing, check that the protocol and name look right. If the list is empty, check the update result instead of scanning the same code repeatedly.

Select a node and start the connection. The first time, Android will ask you to confirm the VPN connection. This permission lets the client create a local virtual network interface to route traffic; it doesn’t mean the remote node has connected successfully. A key or VPN icon in the status bar only confirms that the system interface is up. Verify the connection with a real web request and the client logs. The icon may remain visible even if configuration parsing fails or the server rejects the connection.

Per-App Proxy Rules and Background Activity

Android clients often route app traffic through the system VPN interface. This is different from changing the system proxy on desktop. If you enable per-app rules, check whether the list means “only proxy selected apps” or “bypass selected apps.” Choosing the wrong option can completely reverse your browser test results. Start with the default settings and a clearly defined scope, then narrow it once the connection is stable. Retest the same apps after every change.

Android generally allows only one standard VPN service to be active at a time. Other VPNs, some firewalls, and local-VPN-based filtering tools may compete for the same connection. Always-on VPN and “Block connections without VPN” can also affect what happens after disconnecting, so check these system settings before stopping the client. If every app loses network access, don’t assume the node is at fault; Android may be enforcing your blocking policy.

If the connection drops when the screen locks but works in the foreground, check battery optimization, background activity, and manufacturer restrictions on auto-start. Grant suitable background permissions to the client you use, but don’t disable power-saving features across the entire device. Check whether the connection recovers when switching between Wi-Fi and mobile data. If it fails on only one network, compare DNS, authentication, and reachability on that network. Keep the node, app, and destination the same during testing; don’t mix network switching with subscription updates.

Routing and DNS: Choose an Exit for Each Connection

The system proxy and TUN determine how traffic enters the client; routing rules determine where it goes next. Neither replaces the other. If an app’s traffic never reaches the client, switching to “Global” won’t capture it automatically. Traffic that does reach the client may still be routed directly by a rule. Confirm the entry point first, then check the exit. Desktop presets such as “Bypass mainland China,” “Blacklist,” and “Global” represent routing strategies; check the client’s current configuration for the actual rules.

Rule Order and Direct-Connection Exceptions

Cores generally evaluate routing rules in order, and the first match determines how traffic is handled. Rules that preserve LAN access need to fit sensibly alongside application rules. An overly broad direct rule near the top may prevent later proxy rules from ever matching. Domain rules only work when the core knows the domain; direct IP connections, apps that resolve domains in advance, and connection reuse can all affect what you observe. After changing rules, test with a new connection, since existing connections may keep using the old route.

The Xray-style routing snippet below only demonstrates direct routing for private IP addresses; it is not a complete, standalone configuration. Before merging it, confirm that the actual configuration has a direct outbound named direct, and place the rule in the right order. Graphical clients may generate configuration files at startup, so manual edits can be overwritten the next time the client starts. Use the client’s rule management interface for rules you want to keep.

{
  "routing": {
    "rules": [
      {
        "type": "field",
        "ip": [
          "geoip:private"
        ],
        "outboundTag": "direct"
      }
    ]
  }
}

DNS Resolution and Rule Databases

GeoIP data is mainly used to classify IP addresses, while GeoSite data is mainly used to match domain collections; they are not interchangeable lists. geoip:private matches private IP addresses, while geosite:cn references a domain collection. Missing databases, unsupported rule names, or formats incompatible with the core can all prevent rules from loading. After updating, check the logs to confirm the data loaded, then test a specific request. A completed download alone doesn’t prove that the rules are working.

DNS controls how a domain is resolved; routing controls where the connection goes. The two can affect each other. The wrong DNS path may return an unreachable address or leave a connection with only an IP address when routing rules need the domain. First identify whether the app, system, or core handles resolution, then check whether DNS requests go direct or through the proxy. A browser’s built-in secure DNS may not behave as the client expects. During troubleshooting, use one DNS path at a time instead of changing several settings at once.

When to Use FakeDNS with TUN

FakeDNS maps virtual IP addresses to domains so the core can recover domain information for later connections. It doesn’t mean the real server has moved to that virtual address, and it isn’t compatible with every app. App caches, routing exclusions, and DNS requests that don’t use the same mapping process can cause virtual addresses to be used incorrectly. Enable it only when the client, core, and traffic-capture path are compatible. It isn’t a universal fix for DNS problems.

LAN printers, internal domains, and corporate networks often need specific DNS paths. If internal services stop working after you change DNS settings, restore the original settings first, then add explicit direct-routing and DNS exceptions. For more on configuration fields, see the config.json structure guide. For database updates, see the GeoIP and GeoSite database guide. For virtual address mapping, see how FakeDNS works.

Connection Checks: From the Local Listener to a Real Request

Don’t judge a connection by a single “running” status. The full path includes the client process, core listener, app traffic capture, routing match, remote handshake, and destination response. One layer working doesn’t prove the next one is healthy. Start with one browser request through the system proxy, then test an app that doesn’t read system proxy settings, and only then consider TUN. On Android, first confirm that the VPN interface is up, then check the active node and app scope.

Run a Reproducible Connection Test

Record your current network, active node, proxy mode, routing mode, and test destination. Then change one thing at a time. First open a known-reachable page to confirm your basic connection. Next, enable the proxy and visit the destination you want to test. Use a new connection for each test; close old tabs or restart the test app if needed so cached results don’t make a connection look healthy. A successful client test means only that the specific test passed, not that every app can connect.

If the browser works but a particular app doesn’t, check whether it reads the system proxy, has its own proxy settings, or uses a different protocol. An HTTP proxy can handle common web requests, but that doesn’t mean every UDP app can use the same route. TUN provides a way to capture traffic; the remote node and core must still support the actual traffic. When an app reports a network error, distinguish a timeout, certificate error, DNS failure, and server rejection. Don’t lump them all together as slow speeds.

Read Logs and Test Results by Layer

Authentication failures in the logs usually call for checking the node parameters and service status. A refused connection may mean the destination port is closed or the service isn’t running. A timeout only means the expected step didn’t complete in time; the cause could still be the local network, route, or server. Read error messages in the context of where they occurred. If there’s no matching request in the logs, check the app’s traffic path before changing remote settings. If you need more detail, temporarily increase the log level and restore your usual setting once you’ve found the issue. Avoid logging excessive browsing data over the long term.

Assess Latency, Download Speed, and Stability Separately

Connectivity checks, handshake time, and large-file throughput measure different things. A low ping doesn’t guarantee faster sustained downloads, and one fast result doesn’t prove a long-lived connection is stable. Use the same destination, similar times of day, and the same network for comparisons. Keep an eye on local Wi-Fi signal, bandwidth usage, and server load. Don’t test every node at once and choose based on one snapshot; concurrent tests can saturate the connection and skew the results.

If one node keeps failing, compare it with another configuration. If every node fails on one network but works on another, check the local network path first. If TUN fails but the system proxy works, check permissions, routes, and DNS capture. Writing down these results is more useful than repeatedly reinstalling the client. For a more detailed, layer-by-layer approach, see how to troubleshoot slow V2Ray speeds. The same comparisons can help diagnose intermittent disconnects.

Configuration FAQs: Updates, Migration, and Recovery

This chapter covers issues that can affect any platform. First, identify whether the problem started after an update, network change, sleep, rule edit, or client exit. Then decide which layer to restore. The more complex your setup, the more important it is to keep a working baseline: one known-good node, clear proxy settings, and a restorable rules backup. Restore one change at a time to find the actual cause. For common menu questions, see 10 beginner questions about v2rayN.

Subscription Updated Successfully, but Why Can’t I Connect?

A successful update means the client retrieved or parsed something; it doesn’t mean every node is online. Check that configurations actually appear in the main list, that the active node belongs to the group you just updated, and that your account is still valid. If the provider has reset the subscription URL, the old link may return an error. Get the full URL again from your account page. If some fields aren’t recognized after the update, check whether your client and core support the protocol. Don’t delete security parameters just to force the configuration to save.

Manually edited subscription nodes may be overwritten during the next update. If you need to keep a custom configuration, copy it to a separate group using the client’s supported method and note why you changed it. Don’t assume a copied node will continue receiving all updates from the original subscription; the two may no longer be linked. When migrating devices, confirm whether you’re importing a subscription URL, a snapshot of a node, or a full client backup. These behave differently when updated.

Update the Client Before Switching Cores

Before updating, export any data you need, stop active transfers, and exit the old client normally. After updating, test the original node and mode first. Confirm that the basics work before switching cores or changing rules. Client and core versions don’t always change together. An interface recognizing a field doesn’t mean the running core supports that combination. When troubleshooting, note the actual core name and error type; that’s more useful than simply saying the app is up to date.

When switching cores on desktop, check protocol, security mechanism, transport type, and rule format. Two cores may support different subsets of the same configuration; don’t copy custom fields from one core to another without checking. On Android, v2rayNG and v2flyNG are separate apps, so switching also means importing the subscription again and granting VPN and background permissions. If the connection fails only after switching, go back to the known-working combination, keep the comparison results, and then check compatibility.

Restore Your Network in Order After Exiting

On desktop, first check whether the system proxy still points to a local port that has stopped listening. Next, confirm TUN is off, then check DNS and other VPNs. If your browser has its own proxy extension, check that separately. On Android, review Always-on VPN and “Block connections without VPN” to confirm the system isn’t blocking traffic by design. A restart may clear some temporary state, but persistent incorrect settings will return afterward.

When restoring your network, keep any proxy and DNS settings required by your organization or household; don’t reset everything at once. If your computer needs LAN access, first disable the new traffic-capture method and test the original connection, then restore exceptions one by one. If only one device is affected, troubleshoot that device. If every device on the same network has the issue, check the router, upstream connection, or authentication status first. A client can handle only traffic routed through it; it can’t fix a basic network outage.

What to Include When Asking for Troubleshooting Help

Include your operating system, client name, core type, traffic-capture method, steps that trigger the issue, and comparison tests you’ve already run. Share only the relevant log lines around the error and redact subscription URLs, user IDs, passwords, and identifiable server details; there’s no need to send the full configuration. A reproducible report such as “After switching to this mode, this app shows this error” is more useful than “It won’t connect.” To repeat the installation and connection steps, return to the setup guide. To check another package format or architecture, visit the downloads page.