V2Ray Setup Guide for All Platforms

Getting Ready: Understand the Configuration Layers

Client, Core and Connection Settings

V2Ray setup has three layers. The client provides the interface, subscription management and system integration. The core reads the configuration, establishes connections and applies routing. Server settings specify the remote address, port, authentication and transport. Installing a client only prepares the local management tool; it does not provide a working connection. Before you begin, have a subscription URL or individual share link obtained through legitimate means, and confirm that the service is still active.

v2rayN is for desktop systems. v2rayNG is a commonly used Android client with the Xray core, while v2flyNG offers the V2Fly core. Project V, V2Fly and Xray are related parts of the ecosystem, but that does not mean all configurations are interchangeable. Support for a protocol or transport depends on the client's configuration capabilities, the core in use and the server's requirements. Choosing a compatible combination is more effective than repeatedly toggling settings.

Note Your Device Details and Existing Network Settings

Before downloading, check your operating system and processor architecture. Desktop systems distinguish between x64 and arm64; on macOS, also check whether you have Apple Silicon or Intel. On Linux, check whether your distribution uses deb or rpm packages as well as the architecture. Don't guess based on the device's appearance or assume a compatibility layer is the default choice. Compare your system with the requirements on the download page. If you're unsure which interface version to use, see the client comparison.

Also note whether you currently have another proxy tool, corporate VPN, custom DNS or network-filtering software enabled. For your first test, use just one program that takes over network traffic to avoid conflicts over the system proxy or virtual network adapter. Confirm that your regular network can reach commonly used websites before importing a configuration. If the underlying network is already down, subscription updates and remote connections will fail; changing protocol settings at that point only adds more variables.

Subscription URLs and Share Links Are Different Inputs

An address beginning with https:// could be a subscription endpoint or an ordinary webpage; follow the provider's instructions. Links beginning with vmess://, vless:// and similar schemes are usually individual share links, which should be imported from the clipboard or through the relevant import option. Don't paste a share link into the subscription URL field, or use an informational webpage as a subscription URL. A QR code is just a way to carry data; after scanning, check what type of content it contains.

Check the system date, time zone and automatic time settings. A significant clock mismatch can affect TLS certificate validation or cause time-dependent authentication to fail. Then choose a recognizable configuration name to make logs easier to review later. Subscription URLs often contain personal identifiers or access tokens. Hide the full URL before sharing a screenshot or asking for help. Don't paste it into unfamiliar parsing websites or publicly share a QR code that contains authentication details.

A Minimal Test Sequence for Your First Connection

We recommend importing a configuration, selecting a server, enabling one proxy entry point and testing a target app—in that order. On desktop, start with the system proxy. On Android, grant the system VPN permission to establish a connection; investigate TUN only if you've confirmed that the app doesn't use the system proxy. Check the result after each step, and don't change routing, DNS and the core all at once. When you're done testing, check that the system proxy has been restored so leftover settings aren't mistaken for an underlying network problem.

Windows: Install v2rayN

Choose an Installer Based on the Interface and System Requirements

Go to the Windows download page and check the listed system requirements. The v2rayN desktop edition uses a cross-platform interface, while the classic WPF edition retains the traditional Windows desktop experience. They don't connect to different services, and you don't need to install both to get connected. If you're new to v2rayN, start with the option recommended on the download page. If you already have a preference, choose based on the interface, system support and runtime requirements. See Desktop Edition vs. WPF Edition for details.

The Windows download on this page is an x64 package. Check your device architecture under “About” in Windows Settings first. Follow the installer wizard to complete setup. If you downloaded a compressed package, extract it fully before launching the app; don't run it from the archive viewer. A writable directory helps preserve logs and settings, but don't move a program directory that's already in use without a reason. If startup reports a missing runtime component, install the required dependency for your architecture. Avoid repeatedly downloading unverified runtime bundles.

Import a Subscription and Select the Active Server

Open v2rayN and add a group under “Subscription Group Settings.” Enter a recognizable name, then paste the full subscription URL into the “Address (URL)” field. Make sure the group is enabled and save it, then update the subscription. Before establishing your first connection, try the update option that does not use a proxy. If the provider explicitly requires a particular network path, follow its instructions. When the update finishes, check that configurations were actually added instead of assuming success because the dialog closed.

Select the server you want to use from the imported configurations and set it as the current server. Enabling a subscription group, selecting a server and turning on the system proxy are three separate actions. Missing any one of them can make it seem like a configuration was imported but won't work. If the list is empty, return to the Subscription Management section and check the response and format. Don't guess at ports, IDs or TLS settings and enter them manually; doing so could overwrite a complete configuration.

Start with the System Proxy; Add TUN Only If Needed

Under “System Proxy,” select “Automatically configure system proxy,” then close and reopen the app you're testing. The system proxy provides a local proxy entry point to apps that support the setting; it doesn't force every process to use it. If a browser works but a standalone app doesn't, first check whether that app has its own proxy settings. One app ignoring the proxy doesn't mean the server is unavailable. “Clear system proxy” also doesn't mean deleting your subscriptions.

If you need to route apps that don't use the system proxy, try “Enable Tun Mode.” This feature typically uses a virtual network interface and routing, and may require elevated permissions. Grant permissions as prompted by your current client. After enabling it, check the logs for a successful startup before testing the target app; an enabled switch doesn't guarantee that a network path is working. If it fails, turn TUN off to return to a baseline, then check permissions, components and conflicts with other VPNs. Don't rely on elevated permissions as a universal fix.

Common Windows Issues

If you see a port-in-use error, close any duplicate client instances and check for other proxy software. Don't keep changing the port without updating the app settings to match. Respond to firewall prompts based on how you actually use the client; opening inbound access on public networks is usually unnecessary. Enable “Allow connections from LAN” only if you need to share the connection. For installation details, see Common Windows Setup Pitfalls. After each change, retest with the same app to keep the conditions consistent.

macOS: Chip, Permissions and Proxy

Check Your Chip Before Installing the App

Open “About This Mac” and check whether it reports Apple silicon or an Intel processor. Then choose the matching v2rayN desktop edition from the macOS download page. Apple Silicon uses arm64; Intel uses x64. Don't infer the architecture from the macOS version or purchase year. A package that launches through compatibility support isn't necessarily the best fit. Use the installer that matches your hardware to make permissions and component troubleshooting clearer later.

Open the downloaded disk image and follow the window's instructions to move the app to the Applications folder. Launch it from there. Don't keep running it from the mounted image, as this can complicate upgrades, saved paths and permission grants. If macOS blocks the app, first confirm that it came from the expected download page, then review the specific message under “Privacy & Security.” Use the system's Allow option only for an app whose source you've verified. Disabling all system security checks for convenience is not recommended.

Set Up the Subscription and Know the Difference Between Closing a Window and Quitting

Open Subscription Group Settings, add a name and URL, save, then update the subscription. If you copied the URL from a webpage button, check for spaces or line breaks at either end, and make sure you didn't copy the button label with it. Once the update succeeds, select the current server and test the proxy. Closing the window may leave the app running in the menu bar. Before quitting, decide whether the system proxy needs to be restored. A window disappearing from the desktop doesn't mean the client has stopped.

macOS saves network settings per network service. Wi-Fi, Ethernet and other interfaces can have different proxy settings. If the setup works at home but fails on a different connection, check the active network service before reimporting all your subscriptions. After enabling automatic system proxy configuration, verify the values in network settings. For apps with their own proxy settings, also check that they are set to follow the system rather than using a previously saved address.

System Proxy and TUN Permission Boundaries

Start with only the system proxy enabled. Once you've confirmed that a browser can access the network, decide whether you need TUN. TUN may require system approval, a helper component or elevated permissions, depending on how the current client implements it. If the option isn't available, check the documentation for your build rather than copying service-installation steps from another platform. A permission prompt should correspond to an action you just took; don't approve requests from unknown sources.

After enabling TUN, check that domain names resolve, local network devices remain accessible and the connection recovers after waking from sleep. If only some apps fail after wake, disconnect and reconnect the client, then check whether the active network service changed. Don't delete all system network settings as a first step. If you use a corporate VPN or network extension, test each one separately. When both tools modify routing, the interface can show “connected” even though traffic isn't taking the expected path.

Updates, Migration and Restoring the Connection

Before updating, quit the running app and save any configuration backups you need. Replace the app files afterward. Use the configuration directory option provided by the client to locate backups; don't assume a fixed path. When moving to another Mac, system permissions granted on the old device may not carry over, so you'll need to review them again. If the network stops working after you quit the client, first check whether the active network service still points to a local proxy. Restore the previous value, then re-enable client features one at a time to avoid carrying an old state into a new test.

Linux: Packages and Desktop Environments

Match Both the Package Format and Processor Architecture

Linux installation depends on two things: your distribution's package system and your processor architecture. On the Linux download page, deb and rpm are package formats for different distribution families, while x64 and arm64 refer to processor architectures. Being able to download a file doesn't mean your system can install it. Check your distribution and architecture in the system's About page. If you're still unsure, consult your distribution's package-management documentation instead of trying formats at random.

Open the compatible package in your desktop software installer, review its dependencies and permission prompts, then complete the installation. Resolve missing dependencies through your distribution's standard repositories. Don't manually delete package-manager lock files or assemble shared libraries from unknown websites. If the app installs but doesn't appear in the menu, try signing out and back in to your desktop session, then check the installed apps list. This guide focuses on the graphical client; you don't need to turn a desktop app into a background system service.

Import a Subscription and Test the Local Proxy

Launch v2rayN, open Subscription Group Settings, enter a name and subscription URL, save and update. Select the current server, then check that the client can start the core before configuring the desktop proxy. Linux desktop environments and app frameworks vary, so whether “Automatically configure system proxy” works depends on how the target app reads proxy settings. A proxy address appearing in a desktop settings panel doesn't mean every already-running process has picked up the change.

If you need to configure an app's proxy manually, get the current listening address, port and proxy type from the client, then enter them in the app. Don't use an HTTP endpoint as SOCKS or assume a port from another computer is the local default. For local use only, keep the listening address within the loopback range. If the app reports a connection refusal, check that the core is running and the listening port hasn't changed before suspecting remote authentication.

Distinguish Desktop Proxy Settings, Environment Variables and TUN

Some graphical apps use the desktop environment's proxy settings, some use their own configuration, and some command-line programs rely mainly on environment variables. These are separate entry points and don't automatically stay in sync. A browser working while a terminal app fails doesn't prove that routing rules are wrong. First find out which proxy mechanism the target app uses, then configure the correct entry point. Don't assume every network request uses the proxy just because the system proxy is on.

TUN usually needs access to a virtual network device and permission to change routes, which may exceed a regular user's permissions. If the client reports a permissions error, use the integration method provided for that build rather than running your entire graphical desktop with elevated privileges. Sandboxed installations or restricted sessions may also block access to network devices. If startup fails, save the first clear error in the logs, then check permissions, system components and existing VPNs. Repeatedly clicking the switch won't provide missing requirements.

Desktop Integration and Restoring Network Access

If the tray icon is missing, first check whether your desktop supports the relevant tray extension; its absence doesn't mean the core has exited. If DNS stops working after switching networks, check whether your network-management component has overridden the previous settings, then restore them using the method supported by the client. Don't manually edit several resolver files at once. Some are generated dynamically by the system and may be overwritten the next time you connect, leaving behind seemingly random failures.

Before updating the app, save your configuration and quit the client. Upgrade using the same package-management method to avoid installations from different sources overwriting each other. Before uninstalling, clear the system proxy set by the client and turn off TUN. Removing the app files may not remove proxy values saved in the desktop environment. If the network is still down after a restart, restore the original network settings before reinstalling and testing. Keeping one known-working baseline configuration is usually faster than layering more changes onto complex rules.

Android: Import and VPN Permissions

Choose a Client and the Right Package Architecture

Visit the Android download page. v2rayNG, which uses the Xray core, is the recommended choice; choose v2flyNG if you specifically need the V2Fly core. The two clients don't necessarily have identical interfaces or feature support, so don't expect every setting to transfer just because their names are similar. Most newer phones use arm64, but check your system architecture. If you can't confirm it, consult the universal package details on the download page; screen size doesn't indicate architecture.

When opening the installer, Android may ask you to allow the browser or file manager you used to install apps from unknown sources. This permission applies to the app that started the installation, not the entire system, and you can revoke it afterward if you want. If installation fails, check the package architecture, available storage and source of any existing app with the same name. Don't uninstall immediately if an upgrade fails, as this could erase subscriptions and local settings. First use the client's supported backup method to save anything you need.

Import from a Subscription, Clipboard or QR Code

To add a subscription, open Subscription Groups or Subscription Settings, enter a name and URL, save, then update. The update action may be in a menu, depending on the interface; the essential sequence is to save the subscription entry before fetching its configurations. If you have a single share link, use an option such as “Import from Clipboard.” If you have a QR code, scan it and check the type of item being imported. Don't upload a screenshot of a QR code to a public scanning website; it may contain complete authentication details.

After importing, select a server and tap the Connect button. The first time you connect, Android displays a system VPN permission prompt. Confirm that the request came from the client you just used. Once permission is granted, the client can use the virtual network interface provided by the system to handle traffic. Here, VPN refers to a type of system interface; it doesn't mean you've selected any particular remote protocol. The connection itself depends on the protocol, transport and authentication settings in the current configuration.

Understand How Android Handles Traffic

On mobile, you don't need to copy the desktop “Automatically configure system proxy” workflow. The usual connection mode runs through Android's VPN service. Options for selecting which apps are covered, handling DNS and bypassing the local network depend on the client. For your first test, use the default traffic scope. After confirming that the basic connection works, set up per-app rules if needed. Otherwise, an app outside the selected scope can easily be mistaken for a server problem.

If you've configured per-app proxying, check whether the current mode means “only selected apps” or “bypass selected apps”—the two work in opposite ways. Reconnect after each change, then test the target app. Android generally allows only one standard VPN service to be active at a time. Other VPNs, ad blockers or packet-capture tools may take over the connection. Turn them off during testing and check whether Android has set another client to always-on mode, so it doesn't replace the connection as soon as it starts.

Background Restrictions, Network Changes and Recovery

If the connection works with the screen on but drops after locking, check battery optimization, background activity and the manufacturer's autostart controls. Options vary by device, so relax restrictions only for the client that needs to stay connected; there's no need to disable power saving across the system. The client's persistent notification may be tied to its background service, so don't stop a required service just to hide the notification. A process-termination log points to a different problem than a failed remote handshake; troubleshoot them separately.

After switching between Wi-Fi and mobile data, the existing connection may need to be re-established, and DNS or network access conditions may change. Disconnect and reconnect, confirm that the current network can access the internet, then investigate subscription or server issues if necessary. Whether a hotspot forwards traffic handled by the client depends on the system and device implementation. The phone working doesn't guarantee that devices connected to its hotspot will work too. Before exiting, check Android's “Always-on VPN” and “Block connections without VPN” settings; otherwise, stopping the client may cut off network access for every app.

Subscription Management: URLs, Updates and Backups

Identify the Input Before Choosing an Import Option

A subscription URL lets the client fetch a group of configurations and update them later. A share link usually describes a single connection. Both may arrive by copy and paste or as a QR code, but that doesn't make their input fields interchangeable. Identify the content first, then choose Subscription Settings or the share-link import option. See Share Links vs. Subscription URLs for details. Knowing what you're importing can prevent many parsing errors.

When creating a subscription group, choose a name that identifies its source or purpose instead of a string of indistinguishable numbers. Keep the complete path and query parameters provided with the URL. Don't remove parts just because they look long, and don't share the URL publicly. If you copy it from a chat app, check for localized punctuation, hidden line breaks or truncation. The example https://example.com/your-sub illustrates the field format only; it isn't a service URL that provides configurations.

Separate Subscription Update Failures into Fetching and Parsing

A subscription update has two stages: requesting the URL and reading the response. Request timeouts, DNS resolution failures and TLS errors belong to the first stage. If content downloads but no configurations appear, check the content format and core support. A successful status code can still return a login page, expiration notice or other text, so don't judge by whether the update says it finished. If the client logs include the response type or parsing error, use that information first instead of changing unrelated routing settings.

Choose whether to update directly or through an existing proxy based on how the URL can be reached. A new installation usually has no working proxy yet, so try updating without one first. If the URL is reachable only through an established connection, use the opposite option. If both fail, check the network and whether the URL is still valid. Don't refresh repeatedly or send the full subscription URL to a third party for testing. For more troubleshooting steps, see Troubleshooting Failed Subscription Updates and Empty Results.

Separate Subscription Updates from Local Changes

Configurations in a subscription may be regenerated on the next update. Direct edits to server addresses, names or advanced settings may not persist. To run a comparison test, first copy the configuration to a separate local entry and note why you're changing it. Don't treat a test configuration as an original subscription entry. After updating, check that the selected configuration still exists. The provider may remove, rename or change entries, and an old selection may not automatically map to a replacement.

Automatic updates work well for subscriptions you've confirmed can be fetched, but verify a new subscription manually first. If the client supports an update interval, set it according to your needs; frequent updates won't fix connection problems. An update fetches the configurations currently returned by the provider. It won't resolve a local port conflict or undo an incorrect system proxy setting. Even after a successful update, check the current server, proxy entry point and target app—an updated subscription doesn't prove that you're connected.

Backup Contents and Privacy

Before backing up, check what the export includes. Some exports contain only connections; others also include subscription URLs and preferences. System permissions usually can't be transferred with the backup. Store backup files in a trusted local location, and remove URLs, user IDs and authentication fields before sharing them. On a new device, import and test one configuration before restoring routing and other custom settings. If you suspect a subscription has been exposed, ask the provider to replace the URL or credentials. Deleting the local group alone won't invalidate an exposed URL.

Proxy and Routing: The Entry Point Isn't the Exit

System Proxy, TUN and Routing Each Handle a Different Layer

The system proxy tells apps that support it to send requests to a local listening port. TUN receives traffic within its configured scope through a virtual network interface. Routing rules then decide which outbound handles those requests. These concepts operate at different layers and can't replace one another. Turning on TUN doesn't mean every request goes remote, and choosing global routing doesn't force an app that never sent traffic to the client to use the proxy. Before troubleshooting, ask “Did the request reach the client?” and then “Where did it go?”

For your first setup, start with a routing preset provided by the client. For example, “Bypass mainland China (Whitelist)” uses the local rule resources and actual configuration to match traffic; it doesn't mean every domain is accurately classified by geographic location. Rule files, DNS results and core behavior all affect the final route. Test the default preset first, then add a small number of rules for clear needs. Combining rules from unrelated sources can cause ordering conflicts and mismatched tags.

Rules Match in Order; Outbound Tags Must Exist

Routing typically evaluates rules in order. A broad rule near the top may catch traffic intended for a later rule. Before writing a rule, decide whether to match by domain, destination address, port or app scope. This Xray/V2Ray-style routing snippet illustrates sending a matching domain to the outbound named direct. It's not a complete configuration: add it to an existing routing structure with the corresponding outbound and rule resources already in place.

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

geosite:cn refers to a set of domains in the local geosite data; it can't work if the required resource is missing. outboundTag references an existing outbound; writing an English word there doesn't create one. Tags generated by your client may differ from this example, so use the actual configuration. In a graphical routing editor, choose an existing outbound from the editor instead of mixing in fields exported by another tool.

Check DNS and Rule Matching Together

Domain-based and IP-based matching have different requirements. If the client only gets the destination IP, some domain rules may never apply. If the domain is resolved before matching an address set, the DNS response can affect which rule matches. Don't use repeated DNS-server changes as a substitute for checking the rules. First find out what information the request carries when it reaches the client, then review the domain policy and resolution path. This helps explain why requests to the same website may use different outbounds.

Consider local network access separately. Printers, home storage and router administration pages usually shouldn't go through a remote server, but their traffic may still enter TUN. Use the client's local network bypass setting or an explicit rule rather than disabling all routing. Corporate intranet domains may also depend on dedicated DNS, so switching to a public resolver can break them. If intranet access fails, first restore the original DNS conditions and confirm that names resolve correctly, then adjust the proxy route.

Test a Small Scope Instead of Replacing Everything

Add one rule at a time, recording the target, expected outbound and test result. Reconnect before testing, and restart the target app if needed; existing connections don't always use the new route. Route-match details in the logs are more informative than whether a webpage opens. A working page may have taken a different path. Once a new rule is confirmed, save it to the stable configuration rather than leaving every experiment in the production rules.

If a routing change breaks everything, switch back to the original preset and confirm that the connection works, then compare the added rules. Check JSON commas, array structure, resource names and tag references. Don't change the core and subscription at the same time. For terminology, see the Glossary. If you just want to establish your first connection, return to Getting Started. Advanced rules distribute an existing working connection according to your needs; they don't replace a working network, valid authentication or an active subscription.

Troubleshooting: Narrow It Down by Symptom

Preserve the Evidence, Then Check from Local to Remote

When something fails, note what triggered it, your current network, the configuration in use and the first clear error. Don't immediately clear subscriptions or reinstall the client; that destroys useful clues. A good order is: basic connectivity, system time, local core, listening entry point, current server, remote settings, then complex routing and DNS. Change one variable at a time and record the result before moving on, so you can tell which change actually helped.

If the client interface opens but the core doesn't start, no server can work through the local entry point. Check startup errors such as an unsupported configuration field, restricted file access or a port conflict. A browser's “can't connect to local proxy” message is not the same as a remote handshake timeout in the logs. Get the local service listening first, then test the remote connection instead of describing every symptom as “the node is unreachable.”

How to Diagnose Handshake Failures and Timeouts

If the logs point to authentication or a handshake, compare each setting with the server requirements: protocol, server address, port, user ID, TLS, transport and any required path or service name. The address is the connection target; the TLS server name is used for verification and the handshake. They may differ, so don't swap them based on guesswork. WebSocket paths and gRPC service names are not interchangeable. Preserve details such as capitalization and leading slashes from the original configuration.

For connection timeouts, first check whether the current network can reach the destination, whether only one configuration fails, and whether the behavior changes on another network. If every configuration in the same subscription fails, start with the local entry point and shared settings. If only one fails, check that server's status and transport requirements. Don't disable certificate validation to hide a TLS error; check the system time, domain name and configuration source instead. For a full checklist, see Node Timeout Troubleshooting Checklist.

Connection Established, but Apps Still Don't Work

“Connected” usually means a service or interface has started; it doesn't guarantee that every app request will succeed. If a browser works but another app doesn't, check that app's proxy entry point and traffic scope. If only domain names fail while direct addresses work, investigate DNS. If ordinary network access breaks when TUN is on, turn TUN off and check whether system proxy mode works again. This comparison helps distinguish a virtual interface issue from a remote connection issue without rebuilding the entire configuration.

If parts of a webpage won't load, the cause may involve multiple domains, cached connections or different outbound rules. Reproduce the issue in a clean test window and check the failed request targets in the logs. Don't change rules based only on the main domain in the address bar. Some apps save their own proxy settings or keep connections open; restart them after changing client settings. If per-app proxying is enabled, check whether the target app is excluded and whether the exclusion mode is the opposite of what you expect.

Recovery, Getting Help and Ongoing Maintenance

To restore a working setup, first disable new rules and TUN, then restore the system proxy and DNS and confirm that the underlying network works. Reconnect using your saved stable configuration, then restore custom features one at a time. Before upgrading the client, note the working state and back up the configuration. After upgrading, verify the basic connection first. Don't migrate the core, subscription and routing setup in the same maintenance session. Separate steps take a little longer but leave a clear way to roll back.

When asking for help, provide the operating system, client name, core in use, stage where the error occurred and redacted logs. Hide subscription URLs, user IDs, authentication settings and personal network details, but keep the error type and relevant setting names. For menu locations, return to the relevant platform section. For formats, see Subscription Management; for traffic paths, see Proxy and Routing. Narrow the failure down to one stage before deciding to reinstall. This is usually more reliable than starting over from scratch.