Complete V2Ray Setup Guide for Every Platform

Before you start: Understand the configuration and traffic paths

What the client, core and subscription each do

The graphical client displays servers, manages subscriptions, saves settings and runs connections through a core. The core handles protocols, transports and routing. A subscription is one way to retrieve server configurations: it is essentially a URL that returns configuration data. These three pieces work together, but they are not interchangeable. Downloading a client does not provide a working server, and importing a subscription does not automatically route traffic from every app through the proxy. Before you begin, have a valid configuration ready and decide which apps should use it.

For desktop systems, this guide focuses on v2rayN. On Android, v2rayNG, which uses the Xray core, is the usual choice; consider v2flyNG when you need a V2Fly-compatible configuration. Support for a protocol name does not guarantee support for every related field. Check that the client's core supports options such as REALITY, specific flow settings and transports. Use the server address, port, user ID and security parameters together as provided; never combine fields from different server configurations.

Check your OS, processor and package type

Check your processor architecture in system information, then choose a package from the client downloads page. x64 is common on Intel and AMD desktop processors; arm64 is used by ARM-based devices. Confirm the architecture rather than relying on the brand or appearance of a device. On macOS, distinguish Apple Silicon from Intel. On Linux, check both the architecture and whether your distribution uses deb or rpm packages. If you are unsure which Android package to use, choose the universal build. It is usually larger, but does not provide a stronger connection.

Before installing, note where the old client stores its data, along with subscription group names and custom rules. An upgrade usually keeps existing data; a migration may create a new configuration directory. If you need a backup, use the client's export feature and save the file somewhere you control. Subscription URLs, user IDs and configuration QR codes may contain credentials. Don't post them in public forums or paste them into online formatting tools.

Start with a minimal, verifiable setup

For your first test, run just one client, select a server known to work and leave out custom DNS, complex routing rules and other traffic interception tools. Other proxies or virtual networking software can conflict over ports, routes and DNS. Quit those programs completely rather than just closing their windows. Check that the system date, time zone and automatic time sync are correct, too. A badly incorrect clock can interfere with secure connection checks and make a working server look faulty.

Check the connection in four stages: Was the configuration imported? Did the core start? Is the app sending requests to the client? Is the client routing those requests successfully? Change one stage at a time and note what happens. For example, if the server is already listed, don't keep deleting and recreating the subscription group. If a browser works but another app doesn't, check how that app connects before switching protocols. This narrows down the problem while preserving the parts that already work.

Windows: Install v2rayN and configure the system proxy

Choose the desktop or classic WPF edition

Open the Windows downloads and choose v2rayN. The desktop edition uses a cross-platform interface; the classic WPF edition keeps a Windows-style workflow. Their layouts and data locations may differ, so don't assume a control appears in the same place in both. For a new installation, choose either edition and complete setup. If you already have a stable workflow, stick with the edition you know. Both require a compatible runtime and core files; follow the installer prompts.

Run the installer, choose an installation location and launch v2rayN from the Start menu or app list. If it reports a missing runtime component, note its name and architecture, then install it through a trusted system channel. Don't download a similarly named file from an unfamiliar pop-up. If no window appears after launch, check the system tray; the client may already be running in the background. Before launching it again, confirm that another instance isn't already open, or later port conflicts will be harder to diagnose.

You usually don't need to run v2rayN as an administrator to use the system proxy. Network interception, virtual adapters and other system-level actions may require additional permissions. If security software raises an alert, confirm whether it refers to the installer, graphical client or core, and check the file location. Don't leave system protection disabled just to launch the app. If the app exits immediately, save the error message and check that installation completed, the data directory is writable and security software hasn't quarantined a required file.

Add a subscription, update it and select a server

Open subscription group management and add a group. Give it a recognizable name, then paste the full subscription URL into the address field. The name is just a local label and doesn't affect the connection. Query parameters are part of the URL, so include everything after the question mark and remove any quotation marks or line breaks added by a messaging app. Save the group, update the subscription and wait for server entries to appear. Then select the server you want to use and make it active.

For the first update, use a method that works on your current network. Some interfaces offer both direct updates and updates through a proxy; if you don't have a working proxy yet, updating through one can create a dependency loop. A URL that displays text in a browser may still be unreadable to the client: it could return a login page, an error page or an unsupported configuration format. If the list remains empty after an update, check the subscription error first instead of entering unknown fields in the server editor.

Updating a subscription may replace its entries, including local changes, so don't assume manual edits will survive. If you need a custom server to persist, copy it into a separately managed entry using a method the client supports, and make sure updates won't overwrite it. After importing, confirm that the selected server belongs to the intended group. A long list of servers doesn't mean the active server has changed; the client may still be using the previously selected configuration.

Enable the system proxy, then decide whether you need TUN

In the system proxy menu, select “Set system proxy” so apps that follow Windows proxy settings send requests to the local client. Reopen a browser page to test. Start with a standard routing preset provided by the client, such as “Bypass mainland China,” rather than importing complex rules from an unknown source. If an app is unaffected, check whether it uses the system proxy. Games, command-line tools and some built-in networking components may connect independently.

System proxy: Set system proxy
Routing: Bypass mainland China
Active server: Select an imported configuration
TUN: Enable only if your apps need it

Enable TUN and grant permission only if an app that ignores the system proxy needs to be routed. If enabling it prevents the system from resolving domains, turn TUN off, verify that the system proxy still works, then check the virtual adapter, DNS and conflicts with other networking software. If the browser still can't connect after you quit the client, check whether Windows proxy settings still point to a local address. “Clear system proxy” removes the entry the client set; it doesn't delete subscriptions. “Do not change system proxy” won't remove settings left behind earlier.

macOS: Chip selection, permissions and traffic routing

Install the build for your chip and handle the first-launch alert

Check your chip in About This Mac, then choose v2rayN from the macOS downloads. Apple Silicon uses arm64; Intel uses x64. Open the disk image, copy the app to Applications and launch it from there. Avoid running it directly from the mounted disk image: updates, permissions and launch paths can become inconsistent. Once installation is complete, eject the disk image. Use the copy in Applications from then on.

If macOS blocks the app on first launch, verify the download source and the app name shown by the system. Then follow the current instructions in System Settings under Privacy & Security for the specific blocked launch, and choose to allow the app to open. Labels and button locations vary by macOS version; don't disable system security to bypass an alert for one app. See macOS first launch and permissions for more details.

Opening the app and running its core are separate steps. After the window appears, check the core startup result and confirm that the data directory is writable. If macOS requests network permissions again after you move the app from Downloads to Applications, verify which app the prompt refers to and respond accordingly; earlier approval may not cover a new path. If launch or permission issues persist, quit normally and reopen the app from its fixed installation location to avoid running multiple copies.

Import a subscription and confirm the active configuration

Add a subscription group, enter a name and the full URL, save it and update. Subscription URLs often contain access tokens, so after pasting, check that the protocol at the beginning and all parameters at the end are intact. For a single-server sharing link, use the corresponding import option rather than entering it as a subscription URL. Both types of import may appear in the server list, but they are updated differently. Similar-looking entries don't make the import methods interchangeable.

After the update, select a server as the active configuration and start the connection. If the same subscription works on another device, use it as a comparison point, but don't rule out platform differences: core support, system time, network conditions and DNS can all differ. Keep the original transport and security fields rather than changing unfamiliar values to defaults. Server name indication, transport paths and public-key options can all affect the handshake.

The system proxy handles network services; TUN needs extra permissions

For a regular browser, first enable automatic system proxy configuration in v2rayN and check whether the active network service received the settings. macOS proxy settings are tied to network services, so Wi-Fi, Ethernet and other connection types may have separate entries. If a setup that worked yesterday fails today after you switch networks, check the active service rather than an old connection's proxy page. Grant any permission requested by the system when the app changes network settings.

If the browser works but an app still connects directly, check whether it has its own proxy setting. To route more IP traffic, consider TUN, which may require additional network permissions or a helper component; follow the client's prompts. The system account password requested in an authorization dialog is not your subscription password. If local network devices stop responding after enabling TUN, check whether local subnets are bypassed and whether another virtual networking service is changing routes.

Before quitting, stop the connection and clear the system proxy set by the client, then check whether normal network access is restored. If the client exits unexpectedly while the system still points to a local port that is no longer listening, the browser may report that it can't connect to the proxy server. Remove the leftover proxy in system network settings; there's no need to delete the subscription or reinstall the app. When moving to a new computer, reimport the subscription and grant system permissions on the new device. A backup from the old device can't replace new permission approvals.

Android: Configure v2rayNG and v2flyNG

Choose a client and the right package architecture

Open the Android downloads. For typical use, start with v2rayNG; choose v2flyNG when you need a V2Fly-compatible configuration. These are separate apps, not different skins of the same client, and their core features and settings can differ. Check protocol extension support before switching between them in trial and error. A protocol abbreviation in a server name doesn't confirm that all its settings are compatible; inspect the actual configuration.

Check your device architecture and choose arm64 or the universal package. Most recent phones use arm64, but processor support doesn't guarantee the system provides the required app runtime; system information is the best guide. If the installer reports an incompatible format, return to the download page and choose the universal package instead of repeatedly opening the same file. If Android asks you to allow app installation from your current file manager or browser, grant permission only to that source. You can revoke it after installation if you prefer.

If an app with the same name is already installed, an upgrade failure may be due to the signing source, architecture or a system restriction. Don't uninstall it as a first step; that can remove local subscriptions and custom settings. Check where the existing app came from, export any configuration you want to keep and note the subscription groups. You can install both clients, but don't let them compete for the device's VPN connection. Stop one before testing the other, and check whether networking tools in a work profile are still running.

Import a subscription and start VPN mode

Add a group in subscription management, enter a name and the full URL, save it, then return to the main screen and update the subscription. If the provider supplies a QR code, use the client's scanner after confirming whether it contains a single-server configuration or a subscription URL. Match the import method to the content. QR codes and subscription URLs can be just as sensitive as each other; hide them when taking screenshots of configuration pages, not just the server name.

Once the update adds server entries, select one and tap Connect. The first time you connect, Android usually asks permission to create a VPN connection; you must explicitly allow it. This creates a local interface for routing device traffic. It doesn't provide a remote server or ask you to buy a subscription. If the connection stops immediately after permission is granted, check the client logs or error message to see whether configuration parsing failed, the core failed to start or a network error occurred after the connection began.

Use VPN mode to route traffic from other apps through the client. A mode that only provides a local proxy listener requires each app to configure its own proxy and is best for specific use cases. The VPN icon in the status bar only shows that the system tunnel is active; it doesn't prove that a destination is reachable. After connecting, test the target app and check the related client logs. A changed Connect button or a system icon alone isn't a complete connection test.

Set up per-app routing, LAN access and background operation

With an allowlist, only listed apps are routed through the proxy; with a denylist, selected apps bypass it. Check which mode is active before editing, so you don't put apps to proxy in a bypass list. You may need to reconnect the VPN for changes to take effect. If a browser works but another app doesn't, check the list and that app's network permissions, then check whether the server supports its required transport. There's no need to reset the entire client right away.

VPN mode: Route app IP traffic
Bypass LAN: Keep access to local network devices
Per-app proxy: Check the allowlist or denylist first
Mux multiplexing: Change only when compatibility is confirmed

Disconnects after the screen turns off, followed by a reconnect when you return to the app, often point to background battery restrictions. Check the client's background activity settings under Battery and allow background operation if needed. Menu labels vary by manufacturer, so don't follow paths from another phone. If the connection drops when switching from Wi-Fi to mobile data, reconnect and check that the new network can reach the server. If only one network fails, investigate DNS, network access policies and the server endpoint rather than blaming battery optimization for everything.

Linux: Packages, desktop proxy and TUN

Install v2rayN for your distribution and architecture

On Linux, use the v2rayN desktop client. Check your distribution's system information for the CPU architecture and package format, then choose a matching installer from the Linux downloads. Debian- and Ubuntu-based systems commonly use deb; Fedora and similar distributions commonly use rpm. Compatibility also depends on the distribution version and available dependencies. The package extension identifies the package system, but doesn't guarantee that every distribution using it meets the app's requirements.

After downloading, open the package with your distribution's software installer, review the dependencies and prompts, then confirm installation. If dependencies can't be met, save the full error message and check the package architecture, distribution and software repositories. Don't force installation by ignoring dependencies; the app may appear installed but fail to launch. Start it from the application menu. A graphical client requires a desktop session; a server accessed only through a remote terminal can't use these desktop steps as-is.

Launch the graphical app as a regular user. Running the entire client as an administrator may create configuration files owned by the administrator, then prevent your regular account from saving settings. If writes fail, check the app's data directory and file ownership rather than opening up permissions across your whole home directory. If the distribution's security controls block a network action, check exactly what was denied and follow the platform's recommended process instead of disabling access controls altogether.

Import subscriptions and understand desktop proxy differences

Create a subscription group, enter a name and URL, save and update, then select an active server. The process is the same as on other desktop platforms. When an update fails, distinguish between the client being unable to reach the URL and the downloaded content being unreadable. If the URL returns a login form or network access page, complete the network's sign-in first. On Linux, a browser may open the URL while the client cannot, because they use different proxy settings or DNS paths.

Which apps use the system proxy depends on the desktop environment and each app. Some read desktop settings, others use their own configuration, and command-line tools may use environment variables. Even when v2rayN reports that automatic system proxy configuration is enabled, not every terminal program will use it. Test with an app known to follow desktop proxy settings and confirm the local listener is running before troubleshooting a specific program. Don't change system-wide routes and DNS just to fix one command-line tool.

Environment variables also have limited scope. Changing a variable in the current terminal session won't pass it to a graphical app that's already running, and desktop setting changes may not update the environment of an open terminal. If the target program supports an explicit proxy, enter the local address, port and protocol that the client actually listens on. HTTP and SOCKS proxies aren't interchangeable just because their port numbers look similar; check the client settings for the listener type.

TUN permissions, virtual interfaces and recovery

Consider TUN only when you need to route apps that don't support proxy settings. It involves a virtual network interface, routes, DNS and permissions; it's not simply a stronger system proxy. First check whether the client and distribution support TUN, then follow the client's prompts to grant permissions or configure a helper service. Permission requirements vary by distribution. Don't run an unfamiliar privilege-escalation command indefinitely, or apply setup steps from another platform to your Linux system.

If enabling TUN cuts off network access, turn it off and check that the original system proxy still works. If the network remains broken, check the active DNS and default connection in your network manager. The virtual interface itself isn't necessarily a problem; what matters is whether routes still send traffic through a path that has stopped. These commands only display status and don't change network settings. They apply to systems with the corresponding network tools; if a command is unavailable, use your distribution's equivalent status screen.

ip route show
resolvectl status

When checking routes, look at how the default gateway relates to the virtual interface. When checking DNS, note which network connection provides each resolver; don't delete addresses just because there are several. If containers, virtual machines or another VPN are running, stop the traffic interception tools one by one and see which change causes the conflict. After quitting the client, make sure the desktop proxy isn't still set. Reinstalling the app usually won't fix routes left behind by other components, so keep a reliable way to disable traffic interception and restore normal networking.

Traffic routing: System proxy, TUN and routing rules

Choose how requests enter before choosing where they go

The system proxy, TUN and routing rules solve different problems. The system proxy tells apps that follow system settings to connect to the local proxy. TUN receives IP traffic through a virtual interface at the network layer. Routing rules decide which outbound connection handles requests that have reached the core. A “global” mode is usually a routing preset from the client; it doesn't guarantee that traffic from every app reaches the client. An app that ignores system proxy settings may still connect directly, even when routing is set to global.

That's why it's best to test a browser with the system proxy before considering TUN. With a regular proxy, problems are mainly related to the app's entry point, listening port or server configuration. TUN adds virtual interfaces, routing tables, permissions and DNS to the mix. Add those variables only when you need broader traffic routing, rather than enabling every switch for a more complete-looking status. If an app has its own proxy settings, check that they won't route traffic twice through system or virtual network settings.

Understand rule order and data files

Routing rules are usually checked in order. Once an earlier rule matches, later rules may not be evaluated. If a domain is connecting directly when it should be proxied, check the rules near the top first instead of just confirming that a proxy rule exists at the end. Domain rules rely on domain information available in the request; IP rules depend on the destination address and DNS strategy. They aren't always equivalent. If an app connects to an IP directly, or resolves a domain before traffic reaches the core, the matching information may differ from what you expect.

GeoIP and GeoSite are rule data, not server configurations. GeoIP provides IP address categories; GeoSite provides domain categories. The available categories depend on the data files installed. Client presets can refer to these datasets, but third-party files don't necessarily use the same category names. If switching data sources causes an error about a missing category, check that the rule references match the file contents. For update instructions, see routing data files.

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

DNS, LAN access and multiplexing: When to adjust them

If a domain won't open but the destination IP responds, DNS is worth investigating, but don't assume a particular public resolver is at fault. The client, operating system, browser and app may all use different DNS paths, and caches may keep old results. First identify which app is affected, whether it uses its own encrypted DNS and whether TUN is routing system DNS. Change one setting at a time, reconnect and retry the request to avoid settings overriding one another.

When accessing printers, shared folders or local admin pages, keep an appropriate direct route to your LAN. Bypass-LAN rules typically cover private addresses, but the exact subnets and domain discovery behavior depend on your rules and network. Don't route every destination directly just to reach a local device, or assume one domain rule will make local device discovery work. Test the device's LAN address first, then check name resolution and the app's discovery method. This helps separate basic connectivity from automatic discovery.

Mux multiplexing reuses connections; it isn't guaranteed to work better with every network and protocol combination. If a specific protocol or app has problems, disable multiplexing for comparison while keeping other settings unchanged. Don't also switch servers, transports and DNS. Apply the same approach to custom configurations: save the original rules before making one clearly defined change. Client-generated and hand-edited configurations may override each other. Before editing, confirm which file is actually in use; saving a file successfully doesn't mean its settings have taken effect.

Troubleshooting: Trace the problem from subscription to destination

Subscription update fails or imports no entries

First determine whether the failure occurred while requesting the URL or parsing its response. A subscription domain that won't resolve, a connection timeout and an access-denied response indicate different stages. If the response isn't a supported configuration format, check the subscription type and returned content. When copying the URL, remove leading or trailing spaces and line breaks, and make sure query parameters aren't missing. A URL displaying in a browser doesn't prove that the client received a configuration; the response may be a login form, network authentication page or browser-oriented management screen.

If you already have a working server, try updating directly or through the proxy, depending on your network, and see whether the error changes. If you don't have a usable configuration yet, don't rely on a proxy that hasn't been set up to complete the first update. If the provider changed the subscription URL or access token, use the new full URL instead of guessing which part changed. Failures across several devices point toward the subscription source or service; if only one device fails, compare its network, clock, DNS and client settings first.

Server is listed, but the core won't start or the handshake fails

Once entries appear in the subscription list, confirm the correct server is active and check the core startup result. Configuration parsing errors usually happen before a remote connection is attempted; check field support and core compatibility. If the address won't resolve, troubleshoot DNS first. A connection refusal generally means the destination is reachable but nothing is accepting connections on that port. A timeout only means the connection wasn't completed in time; it doesn't identify whether the cause is the local network, remote firewall or server process.

For handshake errors, compare the complete set of security and transport parameters, including server name, transport type, path, user ID and related extensions. The server address and the name used for secure connections may differ; don't delete one just because they look redundant. A badly incorrect system clock can also cause verification failures. Don't use certificate verification bypasses as a permanent fix. Check the certificate name and validity period, configuration source and network intermediaries, then restore security settings that match the server.

If the same configuration works in v2rayNG but not in v2flyNG, check for core feature differences before assuming that one app is broken. Desktop clients can also update at a different pace from their bundled core features. For a comparison of protocol support, see Xray and V2Fly core differences. Keep the network and server the same and change one variable at a time to make the results useful.

The client shows connected, but apps still can't reach the internet

Separate “the app's traffic isn't reaching the client” from “the traffic reaches the client but can't get out.” If the client shows no request when you use the target app, check the system proxy, per-app lists, app-specific settings and TUN scope. If a request does appear, inspect the matching routing rule and remote error. If only some sites fail, compare DNS results, routing and the destination service. Browser caches, reused connections and background processes may keep using old connections, so make a new request after changing settings before drawing conclusions.

If the local listener won't start, check whether another client is using the same port and whether a previous process is still running in the background. If you change the port, update any app configured to use the proxy manually; otherwise the app and client will no longer match. If problems start only after enabling TUN, switch back to the regular proxy and confirm the server works before checking permissions, virtual interfaces, DNS and other networking tools. Don't add more traffic-routing complexity before verifying that the regular proxy works.

Restore normal networking and collect useful details

To restore normal networking, stop the connection and TUN, clear the system proxy set by the client and check that no other proxy process is running. On Android, confirm that the VPN has stopped and check whether the system is set to block connections without a VPN. On desktop systems, check app-specific manual proxy settings too; clearing the system proxy doesn't always reset them. Once normal networking works, establish a new test baseline with one active server and one traffic entry method.

When reporting a problem, include the platform, client name, stage where it occurred, steps that triggered it and logs closest to the time of failure. Before sharing, remove subscription URLs, user IDs, server credentials and QR codes. Don't upload the entire data directory. For help understanding log messages, see v2rayN log error explanations; for quick answers, visit the Help Center. A clear sequence that reproduces the failure is more useful than a large set of screenshots with no time context.