V2Ray Setup for Every Platform

Before You Start: Platforms, Subscriptions and Configuration Layers

Know the Difference Between the Client, Core and Server Settings

v2rayN, v2rayNG and v2flyNG are the interfaces for configuring and running the software. The client stores server details, generates core configurations, displays logs and provides system proxy or VPN integration, depending on the platform. Xray and V2Fly are core families that handle connections and routing. Installing a client doesn’t give you a working server: the server address, port, authentication details, transport and TLS settings must come from your service provider. You can’t infer these fields from a protocol name alone, or combine credentials from an unrelated configuration with an existing address.

A connection typically passes through several stages: the app, the local proxy, core routing and the remote server. If an app doesn’t send requests to the local proxy, changing the remote protocol won’t help. If the core hasn’t started, switching browsers repeatedly won’t fix the problem. Start by understanding these layers, then change just one at a time as you test. Note your existing system proxy settings, whether another VPN is running, your current network type and where the client stores its configuration. This makes it easier to restore your original network settings after testing.

Check Your Processor and Package Type

On the client downloads page, choose your operating system first, then select your processor and package format. Windows Desktop and WPF are interface variants, not different proxy protocols. On macOS, distinguish Apple Silicon from Intel. Linux packages depend on both processor architecture and distribution format. For Android, arm64 is usually the first choice; check the universal build if you’re unsure about compatibility. The same file extension doesn’t mean the same architecture, and being able to download a file doesn’t mean your device can run it.

Prepare a Subscription and Recovery Materials

A subscription is usually a URL that returns a set of server configurations. It’s not an account dashboard or a plan purchase page. Only enter a link in a subscription group if the provider says it’s intended for client import. This guide uses https://example.com/sub?token=xxxx to illustrate the format; it doesn’t provide a working service. Real subscription URLs may contain access credentials. When sharing screenshots or logs, or asking someone for help, hide the full query string, user identifiers and server authentication details.

Keep a configuration backup somewhere only you can access, and check that your device’s date, time and time zone are correct. TLS certificate validation depends on the system clock; a significant time difference can cause several otherwise working configurations to fail. For your first test, don’t enable the system proxy, TUN and another VPN at the same time. Pick one connection method, verify it works, then expand as needed. On a work or school device, check whether device management policies allow network changes. Don’t treat repeated permission prompts as a reason to grant access without checking who is requesting it.

Prepare two test targets: a page that normally works without a proxy, to check whether direct access is affected, and a destination that should be reachable through your current proxy configuration, to verify the proxy path. Record the target, time and connection method—not just “the network isn’t working.” To set up your first connection, start with the quick start guide. This reference also covers installation, permissions and recovery, so you can look up just the steps you need.

Windows: Install v2rayN and Set Up Proxy Access

Choose Desktop or WPF and Install

Go to the Windows downloads. v2rayN offers the Desktop edition and the classic WPF edition. Desktop uses a cross-platform interface; WPF retains the classic Windows layout. Your server settings don’t turn into a different protocol just because you choose a different interface. For a first installation, pick one edition. Don’t run both at once, as they may compete for local ports. If you need to compare the interfaces, exit the running instance before opening the other edition, and keep separate configuration backups.

Follow the installer prompts, then launch the app from its normal shortcut. If you’re using a portable directory, extract all files to a location where you have write access. Don’t run the app from inside an archive preview or copy only the main executable and leave out its supporting files. The program, user configuration and log directories may vary by installation method; use the client’s open-folder option to find them. If startup reports a missing runtime, check which .NET Desktop Runtime is required, along with your architecture and interface edition. Don’t substitute a similarly named runtime.

Import a Subscription and Select a Server

Open “Subscription Groups,” add a group with a name you’ll recognize, enter the subscription URL in the address field, save it, then update the group. A successful update only means the configurations were retrieved. You still need to choose a server in the main window and set it as active. If you have multiple subscriptions, check which group is selected before updating to avoid repeating the operation in the wrong one. For a shared link, use the appropriate clipboard import option; don’t paste the full protocol link into the server address field.

For your first run, keep the default local listening address and check the actual inbound port shown by the client. This guide uses 10808 as an example; use the port shown in your settings and logs, and check which inbound protocol it accepts. Don’t guess whether an endpoint uses HTTP, SOCKS or a mixed mode from the port number alone. Unless other devices on your local network need access, don’t change the listening address to all network interfaces. Exposing it more widely raises firewall and access-control concerns.

Test with the System Proxy First, Then Enable TUN if Needed

Under “System Proxy,” select “Set system proxy.” Then test with a browser that uses the Windows system proxy. “Clear system proxy” removes proxy settings applied by the client. “Do not change system proxy” means the client won’t actively rewrite existing settings on startup or when switching modes; it doesn’t clear a previously configured proxy. If your browser has its own proxy extension, temporarily disable its rules to prevent them from overriding the system settings. For a work-managed browser, check whether your organization has locked its proxy settings.

Consider TUN only if you need to handle apps that don’t use the system proxy. Before enabling it, close other tools that take over virtual network adapters, note your current network state and grant only the permissions the client requests. TUN affects virtual interfaces, routes and DNS. If the connection fails, switch back to the verified system proxy mode instead of repeatedly changing servers. Whether elevated permissions are required depends on the implementation and how it runs. Don’t run the entire client as an administrator just to update a regular subscription.

Common Windows issues include a non-writable directory, a port already in use, the app running only in the system tray, or a mismatched runtime. Check the taskbar notification area for an existing instance, then look in the logs for listener or permission errors. If your security software reports a block, verify the specific file and its source instead of disabling all protection. For more startup troubleshooting, see Troubleshoot v2rayN Not Opening or Crashing on Startup. Restoring network settings and fixing a startup crash are separate tasks; check them independently.

macOS: Choose the Right Chip, Install the App and Configure the Network

Choose the v2rayN Package for Your Chip

Open “About This Mac” from the Apple menu and check the chip or processor listed. Choose the Apple Silicon package for an Apple chip, or the Intel package for an Intel processor, then get v2rayN from the macOS downloads. Don’t infer the architecture from the computer’s appearance or purchase year, or assume that running another architecture through a compatibility layer is the recommended option. Matching the package to your chip avoids extra variables when troubleshooting runtime and permission issues.

Open the disk image and follow its installation instructions to move the app to Applications. Launch it from there. Don’t keep running it from the mounted image; the path may change when you update or eject it. If macOS warns that the app’s source is unknown or blocks it from opening, first verify the download source and file type. Then check System Settings → Privacy & Security for an option to allow this specific app. Only change the setting for an app you’ve identified; don’t disable macOS security checks entirely to launch the client.

Import a Configuration and Check the Active Connection

In v2rayN, open “Subscription Groups,” add a name and subscription URL, save, then update the group. If the subscription loads but connections still fail, make sure a configuration is selected in the main window and check that the current core supports its protocol and transport settings. A successful subscription update doesn’t mean every server has been tested. If several entries have similar names, check their group and server addresses to distinguish them. Don’t mistake an outdated, manually imported entry for one just retrieved by the update.

For your first test, leave TUN off and use the system proxy. After the client sets it, go to System Settings → Network, select your current connection and check its proxy settings. Ethernet, Wi-Fi and other network services may each have separate settings. If behavior changes after switching networks, check which network service is active instead of relying on the client’s toggle alone. Don’t layer automatic proxy configuration, manual HTTP proxy and SOCKS proxy settings without knowing where each came from.

Understand Permissions for Apps, Terminals and TUN

Some graphical apps use the system proxy; others use their own network stack or proxy settings. Terminal programs don’t necessarily inherit the graphical system proxy, so it’s not unusual for a browser to work while a terminal doesn’t. To use a local proxy for a command, configure it explicitly with a protocol the command supports, and first confirm that the listening port is open. Don’t start by permanently adding proxy variables to your shell startup file. A new terminal could keep trying to use a local endpoint even after the client has exited.

Whether TUN needs extra authorization, a helper component or elevated permissions depends on the client implementation. Follow the interface prompts, then check the logs to confirm that the virtual interface and routes were created. Permission to launch the app doesn’t necessarily include permission to change network traffic paths. If direct-access sites stop working after you enable TUN, turn it off first, then check DNS and network service order. Don’t run another VPN as a workaround: two traffic-interception mechanisms can send routes back through the local machine and hide the original problem.

Before updating, exit the app and back up your configuration to avoid running old and new copies from different folders. If settings seem to disappear after an update, check whether you launched the copy in Applications or an older copy in your downloads folder, then verify the current user configuration location. Before uninstalling or stopping use, clear the system proxy and disable TUN in the client, then check the current network service’s proxy settings. Moving the app to Trash won’t reliably undo all existing network changes; restore your settings before deleting it.

Linux: Package Formats, Desktop Proxy and TUN Permissions

Check Your Distribution, Architecture and Desktop Session

For Linux, identify your package system and processor architecture first. Debian and Ubuntu commonly use deb packages; Fedora commonly uses rpm packages. Check your distribution’s package management documentation for details. Open the Linux downloads and select x64 or arm64. Don’t assume a package is usable just because your system recognizes the archive. v2rayN is a graphical client; this desktop installation guide doesn’t directly cover headless servers or environments without a desktop session.

Before installing, use these read-only commands to check your architecture and system ID. x86_64 usually corresponds to x64 on the download page, and aarch64 usually corresponds to arm64. If you see another architecture, don’t force one of these packages to fit. The system ID helps identify your distribution family, but doesn’t guarantee that all desktop dependencies are installed. Open the downloaded package with your distribution’s software installer or package manager, and review any dependency warnings. Don’t treat forced dependency checks as a general installation solution.

uname -m
cat /etc/os-release

Launch as a Regular User and Import a Subscription

After installation, launch v2rayN from your desktop app list. Start as a regular user and confirm the interface, saved settings and logs work before using network features that need extra permissions. Don’t run the entire graphical app as root to work around a directory permission error. That can create root-owned configuration files that a regular user can’t write to next time. If you already launched it with elevated privileges, locate the actual configuration directory and check ownership. Don’t recursively loosen permissions across your home directory.

Enter the subscription URL under “Subscription Groups,” update it and select an active server. Check the core logs to confirm the local listener started successfully. Linux desktop and network manager combinations vary, so “Set system proxy” may not affect every app. Check the address and port in your desktop environment’s network proxy settings, then test with an app that explicitly uses them. If your browser has separate proxy settings, configure one consistent entry point so it doesn’t keep using a different route.

Test the Inbound Protocol—Don’t Guess from the Port

Terminal programs are often easier to test by specifying a proxy explicitly. The command below is only for a confirmed local SOCKS endpoint; replace 10808 with the port shown in the interface. socks5h sends target hostname resolution through the proxy. With regular socks5, resolution may happen elsewhere. A response confirms that this request used the endpoint; it doesn’t prove that the whole desktop or all protocols are being routed through it.

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

TUN also involves virtual devices, system routes and permissions. After enabling it, check the logs for successful interface creation, then confirm that the default route and DNS changed as expected. If the error occurs before the device is created, changing subscriptions won’t help. Distributions may grant permissions through system services, authorization mechanisms or client-specific methods; follow the software’s instructions. Don’t give unknown files system capabilities or disable firewall rules just because a network problem occurs.

If you lose network access after sleep, switching networks or an unexpected exit, disable TUN first, restore desktop proxy settings, then check the network manager’s connection and DNS settings. Before updating, keep a configuration backup and exit the old process to prevent two cores from competing for a port. Enable autostart only after manual operation is stable, and distinguish between launching the graphical client and taking over system networking. For more on differences between terminal and browser behavior, see Troubleshoot System Proxy Issues by App.

Android: Install a Client and Route Traffic Through VPN

Start with v2rayNG; Use v2flyNG if Needed

Open the Android downloads and start with v2rayNG, which uses the Xray core. Consider v2flyNG if you need the V2Fly core ecosystem. For either app, choose arm64 or the universal build based on your device. Most recent mainstream devices use arm64, but check your device architecture and app compatibility. The universal build is an alternative for architecture compatibility; it doesn’t add protocol capabilities to a server configuration or fix every installation problem.

Open the downloaded installation file. Your device may ask you to allow app installation from the current file manager or browser. Grant permission only to the source you’re using for this installation, and revoke it afterward in device settings if you wish. If you see a parsing error, signature mismatch or installation failure, first check that the download is complete, the architecture is correct and the existing app came from a compatible source. Don’t immediately uninstall the old app. Export a restorable configuration first, then determine whether the issue is package compatibility or a signature conflict between sources.

Add a Subscription, Update the Group and Select a Server

Open the app and add a group with a name and subscription URL under “Subscription Group Settings” or the relevant subscription management menu. Save it, return to the main screen and update the subscription. If there are multiple update options, start with the standard method. If the subscription must be fetched through an existing connection, first make sure the active connection can reach its URL. Don’t tap update repeatedly before the list finishes loading; it makes it harder to tell which operation produced the result. Once the server entries appear, select the one you want to use.

QR code and clipboard imports work well for individual share links; subscription URLs are for configuration sets that can be updated over time. You can use both, but keep track of each entry’s source so you don’t mistake a one-time import for an automatically maintained subscription. If transport, TLS or server name fields are missing, check the original provider details rather than filling them in from a similar-looking configuration. Android may restrict clipboard and file access between apps, so check exactly what the app received if an import fails.

Understand Android VPN Prompts and Per-App Routing

When you tap Start, Android asks you to authorize a VPN connection. This lets the app route selected traffic through Android’s VPN interface; it doesn’t confirm that the remote server is reachable. v2rayNG’s common VPN mode uses a virtual network interface, so don’t assess it using the desktop “system proxy” toggle. If the app also offers proxy-only mode, check whether that mode actually creates a VPN connection. Starting a local listener alone won’t make other apps use it automatically.

Most devices allow only one active VPN to route traffic at a time. Another VPN, a work profile network component or some local filtering tools can conflict with the current connection. Close other traffic-interception apps, then authorize the connection again. With per-app proxy rules, distinguish carefully between “selected apps use the proxy” and “selected apps bypass the proxy”—they do the opposite. Save your choice and reconnect if prompted. Test with a specific app instead of assuming every app is covered because the VPN icon appears in the status bar.

If the app works in the foreground but repeatedly disconnects when the screen locks, check its background restrictions in system battery settings and allow the background activity it needs using the options provided by your device manufacturer. Before configuring “Always-on VPN” or “Block connections without VPN,” confirm that the behavior during a disconnection is what you want. The latter can block network access entirely when the client stops. Before you stop using the app, disconnect within it and check whether Android still requires persistent VPN routing. Mobile data and Wi-Fi can differ in DNS, IPv6 and sign-in requirements; test each separately rather than drawing conclusions from one network.

Manage Subscriptions, Choose a Core and Migrate Configurations

Keep Subscription Updates Separate from Manual Changes

A subscription provides a set of configurations; it isn’t an active network connection. When you update, the client retrieves and parses the content into server entries. When you connect, the core uses the active entry’s settings to reach the remote server. So an unreachable subscription URL, content that can’t be parsed and a server connection timeout are three different problems. Check the update log for network and parsing results, then confirm that entries appeared, and finally test the active connection. Don’t change routing rules to fix a subscription parsing error, or assume that a successful update means a connection works.

Create groups by source or purpose instead of putting every URL in one vaguely named collection. An automatic update may replace subscription-generated server entries, so check whether the client preserves manual changes before editing them. For a configuration you need to keep unchanged, create a separate manual entry and note that it won’t track updates to the original subscription. If the provider changes an address or credentials, update the source URL instead of repeatedly reconnecting with an outdated entry. Before deleting a group, check whether it contains manual entries that haven’t been backed up.

Use Examples Safely and Protect Sensitive Details

The address below illustrates a common subscription format. The actual path and query parameters depend on your service provider; don’t guess them from an example. A subscription may return multiple encoded share links or another format the client can recognize. A browser displaying text doesn’t mean that text is compatible with your import option. If you receive a complete core JSON file, look for the client’s custom configuration import feature rather than pasting the JSON into a subscription URL field.

https://example.com/sub?token=xxxx

When sharing screenshots to report an issue, hide subscription query parameters, authentication IDs, passwords and private server details. A full client configuration export may include subscriptions, manual entries, local listener settings and routing, so don’t share it publicly as routine diagnostic material. To request help, an error excerpt, protocol and transport types, platform, connection mode and reproduction steps are usually enough. If you suspect a subscription URL has been exposed, replace its access credentials through your provider’s management portal. Deleting local history won’t invalidate a URL that has already been copied.

Choose a Core Based on Feature Compatibility

v2rayN’s core setting selects which core runs the configuration; it isn’t a simple performance switch. Xray and V2Fly share ecosystem roots, but support for extensions, transports and parameters may differ. Check what the server requires, then confirm that the client can generate a compatible configuration for the chosen core. If a core doesn’t recognize a field, changing routing mode won’t make it compatible. Likewise, switching to a core that starts successfully doesn’t guarantee that it preserves every custom rule.

Before switching, note the active server, routing and DNS settings. Afterward, check configuration generation and core startup logs, then test a single request. On Android, moving from v2rayNG to v2flyNG means switching apps, not changing cores seamlessly within the same app: add the subscription again, review VPN authorization and background settings, and don’t expect private app data to sync just because server names match. Run only one traffic-interception app at a time so permission conflicts aren’t mistaken for core differences.

Migrate Across Platforms in Three Stages

Migrate subscription or server settings first, routing and DNS second, and local device settings last. Windows system proxy settings, Linux desktop sessions and Android per-app routing aren’t interchangeable. Local ports, configuration paths, autostart settings and TUN permissions belong to the device environment; don’t blindly overwrite them from a backup. Before using a server list’s export or share function, check whether it exports one entry or an entire group. On the destination device, use the import option that matches the export format.

A full backup is best restored in a compatible client environment. For cross-platform moves, use an exchange format explicitly supported by the client. Verify one connection on the destination device before importing in bulk. Don’t retire the old device until subscription updates, routing and network recovery after disconnecting all work. A successful migration isn’t measured by having a similar number of entries; the important checks are correct settings, a working connection, the expected traffic coverage and a recovery path to undo changes.

System Proxy, TUN and Split Routing

Traffic Capture and Core Routing Are Separate Issues

The system proxy determines whether an app sends requests to the local proxy. Routing rules determine which outbound the core uses after it receives a request. Global routing won’t make an app that ignores the system proxy use the client, and TUN doesn’t mean every captured request must go to a proxy server. First confirm the request reaches the core; then check whether it matches a direct, proxy or block route. Understanding the difference helps avoid changing domain rules repeatedly when the problem is actually at the app’s entry point.

v2rayN presets such as “Bypass mainland China,” “Global” and “Direct” are routing strategies; what they do depends on the current rules, outbound tags and data files. Global mode can help briefly verify the proxy path. For everyday split routing, restore the strategy you need afterward. “Direct” doesn’t mean the client is off; traffic may still enter the local proxy and then connect directly through the core. When testing, record both system proxy or TUN status and routing mode. A screenshot showing only that something is “enabled” doesn’t explain the request path.

Understand Rule Fields and Their Order

The routing snippet below can be used in a compatible core configuration; it isn’t a complete startup configuration. The first rule matches a domain set and the second a private IP set. Both use an outbound tagged direct. Your main configuration must define that tag and include the data files referenced by the rules. Without an outbound definition or required data files, copying the snippet alone won’t create a working connection. The client’s routing editor may store rules differently; use its fields instead of overwriting the entire configuration file.

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

Routing rules are usually evaluated in order, so a broad rule near the top can override narrower exceptions below it. Put exceptions for specific domains or local network services before a wildcard rule that would capture them, but choose the order to match your intended behavior. Don’t assume a rule containing both domain and IP conditions matches when either one does; check how the core handles combined conditions. Confirm the default outbound behavior from the complete configuration instead of inferring it from the last rule in a snippet.

Check DNS and Rule Data Together

geosite:cn refers to a domain category in the database; geoip:private refers to a set of private IP addresses. These aren’t labels that update live from the internet, and domain categories may change over time. After updating routing data, check that the core actually loaded the new files rather than an older copy in another directory. For update options and file references, see How to Update GeoIP and GeoSite Rule Files. To understand rule fields and order, continue with Split Routing Rules in Practice.

DNS determines how domains are resolved and can affect which IP-based rules apply. The example’s AsIs strategy doesn’t resolve every domain to an IP just for routing matches. If an app provides only a domain while your rules depend on IPs, choose an appropriate strategy and account for the extra lookup cost. Encrypted DNS in the browser, custom resolvers and TUN DNS interception can also change where resolution happens. Verify a target using domain rules first, then introduce IP matching gradually. Don’t change every DNS path at once.

Before each change, export your routing configuration or save a restorable copy. Add one set of rules at a time, reload and check the logs for the target and outbound. Don’t edit a temporary configuration generated while the client is running; it may be overwritten the next time you switch servers. Once testing is complete, remove global overrides used only for testing and document what your remaining rules do. Reliable split routing depends on a clear relationship between the entry point, DNS and outbound—not a pile of rules from unknown sources.

Common Configuration Issues and Recovery

Troubleshoot in Order of Failure

Start by noting the last action that worked: did the app start, did the subscription update, did the core listen, did the local proxy receive a request, did the remote server complete a handshake, and did the destination return content? This sequence narrows the issue to two adjacent layers. If the logs show that the local port couldn’t be bound, address the conflict first. If there are no request records, check how the app is configured to use the proxy. “Connection failed” isn’t a single diagnosis. Don’t change the client, core, DNS and routing all at once and then guess which change helped.

Empty subscription, core startup failure or only some apps working

If the list is empty after a subscription update, distinguish a failed network request from content the client couldn’t parse. Check whether you copied an account management page instead of the subscription URL, whether there’s trailing whitespace, and whether a filter is hiding the group. If the response is a web page, an error message or an expiration notice, contact the service provider about the subscription instead of trying to connect to an empty list. If the subscription is only reachable through the proxy, first connect with an existing working configuration, then choose the appropriate update method. Otherwise, you can get stuck in a loop: no configuration to connect with, but a connection needed to download one.

When the core fails to start, find the first specific error rather than the last “process exited” message. A port conflict, unsupported configuration field, missing rule data file and unwritable directory each require a different fix. Before changing ports, check whether another client instance is running. Before switching cores, confirm what the server requires. If your configuration contains custom JSON, restore a basic configuration the client can generate, then add your changes back one at a time. Repeatedly clicking Start only creates more logs with similar timestamps; it won’t fix the configuration.

If the browser works but the terminal doesn’t, test the terminal proxy explicitly. If the terminal works but the browser doesn’t, check browser extensions, its independent proxy settings and any managed policies. If only one app fails, check whether it’s included in Android’s per-app routing or uses a separate network stack. In TUN mode, verify whether the request reached the core; don’t assume it was captured just because TUN can do so in principle. For more, see How to Troubleshoot Browser and Terminal Proxy Issues Separately.

Troubleshoot Handshakes, DNS and Intermittent Drops Separately

For a TLS handshake failure, check the system time, server name, transport and parameters required by the provider. Don’t routinely skip certificate verification; that bypasses the protection that verifies the server’s identity. For a DNS failure, first establish whether it’s the server domain or the destination domain—each may use a different resolution path. If only large requests or certain networks fail, note the network type and reproduction steps, then check transport, path MTU or UDP support. A small page loading successfully doesn’t prove that all traffic works.

For intermittent disconnects, check what happened at the time: screen lock, sleep, a network change, subscription update or server switch. On Android, check whether the background process is still running. On desktop, check whether the virtual interface and DNS were restored after the network came back. Restarting successfully doesn’t identify the cause; keep a short, redacted log excerpt from before and after the drop. Increase log verbosity only for as long as needed, then restore the normal level. This avoids unnecessary files and reduces the chance of private destinations staying in logs.

For help, include your platform and architecture, client name, current core, connection method, exact error text and steps you’ve already tested. Subscription URLs, passwords and authentication IDs aren’t needed. If you’ve narrowed the issue to a specific setting, look for the relevant answer in the Help Center. To rebuild a minimal working configuration, return to the Getting Started Guide. Confirm that the connection works, split routing behaves as expected and the network recovers after you disconnect—not just that one page loaded successfully.