V2Ray Setup Guide for
All Platforms

01 / BEFORE INSTALLATION

Before You Begin: System, Subscription, and Network Access

Understand the Client, Core, and Server Configuration

The graphical client stores server settings, manages subscriptions, generates configuration, and starts the core. The core handles protocol connections, traffic forwarding, and routing decisions. For desktop platforms, v2rayN is the recommended choice. On Android, v2rayNG with the Xray core is the usual option; consider v2flyNG if you specifically need V2Fly configurations. Installing a client does not provide a working server or replace the account and service from your subscription provider. Before you begin, have a valid subscription URL or a single-server share link you are authorized to use.

Project V provides background on how these components fit together; it is not a desktop app you need to install. V2Fly and Xray are related core ecosystems, and their capabilities vary by implementation. Whether a configuration works depends on the combination of protocol, transport, security settings, and core support—not just the client name. For an overview, see How Project V, V2Fly, and Xray Fit Together before deciding whether to change cores.

Check Your System Architecture and Install Location

Use the operating system's system information to check your processor architecture; a device's age is not a reliable guide. On Windows, check System Information for the system type. On macOS, check the chip under About This Mac. On Linux, run the command below. The downloads page lists the packages currently available. If the architecture does not match, repeatedly trying to launch the app will not fix it. Decide where to install it in advance: a portable directory must be writable by your user, while application-managed directories are generally not meant for manually added configuration files.

uname -m
cat /etc/os-release

On Linux, x86_64 corresponds to the common x64 package, while aarch64 corresponds to arm64. Distribution details help you choose between deb and rpm; they do not tell you how desktop proxy settings will behave. The operating system, desktop environment, and applications each have their own network settings, so check them separately. For a fresh setup, keep the default directory structure intact to avoid losing bundled resources or runtime components when moving the main executable.

Establish a Network Baseline You Can Restore

Before installing, close any other proxy or tunnel software that is routing traffic, and note the current system proxy settings. Confirm that ordinary internet access works and that the system clock and time zone are correct. An incorrect clock can cause certificate validation to fail; a leftover proxy can send subscription requests to a local port whose app has already exited. The symptoms may look like a client problem even though the failure occurs before the client starts. Avoid changing network adapters, resolvers, and routing presets all at once without a baseline.

For the first test, use the system proxy instead of enabling TUN right away. The system proxy works with apps that follow the operating system's proxy settings, making it a good way to verify browser traffic. TUN routes more traffic through a virtual network interface, requires additional permissions, and can affect DNS, local network access, and other virtual networks. These are not different server protocols, and enabling more features does not make a connection inherently more reliable. Get the basic connection working first, then decide whether to enable TUN based on whether the apps you need follow the proxy settings.

Backups and Privacy

If the device already has a configuration, save it first using the client's built-in export or backup feature. If you need to copy data manually, exit the app first to avoid copying files mid-write. Include subscription groups, routing, custom DNS, and any essential local settings. Subscription URLs often identify your account, and share links may contain credentials. Never post them in public screenshots, discussion threads, or public cloud storage. When asking for help, share only the error type and time, with sensitive details redacted.

02 / WINDOWS

Windows: Install v2rayN and Route Traffic

Choose the Desktop or Classic WPF Edition

Open the Windows downloads section. Check your system architecture, then choose the v2rayN Desktop or Classic WPF edition. The Desktop edition uses a newer cross-platform interface, while WPF retains the classic Windows interface. Both are configuration managers; neither affects server connection quality. If you need to migrate existing settings, back them up first and check whether the new edition can read the old data. Do not let both editions write to the same configuration directory.

Run the installer package through its setup wizard. For a portable package, extract all its contents before launching it. Do not run the app from a compressed archive preview or copy only the main executable. Choose a fixed, writable directory to avoid losing configuration when temporary files are cleared. If startup reports a missing runtime component, follow the package instructions and system prompts to install the required component. Do not download individual DLL files from unknown sources. Keep the exact error message so you can tell a missing runtime from a missing app resource.

Launch the Client, Import a Subscription, and Check the List

When you first open the app, make sure the main window loads correctly, then go to subscription group management. Add a group, give it a recognizable name, enter the full subscription URL, save, and update the subscription. Adding a URL and fetching its contents are separate steps: creating a group does not mean the server list has been retrieved. After the update, check the server list and confirm that basic fields such as protocol, address, and port are populated. Menu wording may change; use the subscription management entry in your current version.

If your clipboard contains a single-server share link, use the client's clipboard import feature instead of treating it as a remote subscription URL. A web link is not necessarily a subscription URL: an account dashboard, a login page, and an endpoint that returns server configurations serve different purposes. If the list is empty after updating, check the request result in the update log, then ask your subscription provider to confirm the URL format and account status. Do not disable certificate validation or remove authentication parameters just to populate the list.

Verify the System Proxy Before Routing More Traffic

Select the server you want to use, set it as the current one, and confirm that the core starts. Then enable automatic system proxy configuration. This lets apps that follow Windows proxy settings use the client's local listening address. Check the port in the client settings; do not copy it from another device. Open a known HTTPS website in a browser and look for the corresponding connection in the logs. If the page does not load, first confirm that the core is running, then check server connectivity. Do not immediately change every routing option.

Not every Windows application follows the system proxy. Some command-line tools, services, and apps with their own proxy settings need to be configured separately. Different networking components may also use different proxy sources, so a working browser does not prove that a node is faulty when another app fails. Check whether the app supports HTTP or SOCKS proxies, then enter the local listening address actually enabled in the client. For local use only, keep the proxy bound to loopback so it is not accidentally exposed to devices on the same network.

TUN Permissions and Shutdown Order

Once the basic connection works, consider TUN mode if the apps you need do not follow the system proxy. First-time setup may require administrator permission, a service component, or a virtual interface, depending on the client implementation. Grant permission when prompted, then check the startup log for successful interface and route creation. An enabled toggle alone does not prove that traffic is being routed: denied permissions, interface creation failures, or conflicts with other tunnels can leave the toggle on while the network path is not working.

If you use virtual machines, a corporate network, or other tunnel software, preserve local network access and test one change at a time. If only some resources work after enabling TUN, check routing and DNS before reinstalling virtual adapters. When finished, disable TUN first, clear the system proxy next, and then exit the client. If the app exits unexpectedly and the browser loses all network access, check Windows proxy settings for a local port that is no longer listening and restore the original settings if needed.

Starting at login and connecting successfully are separate things. First verify that the client starts reliably by hand, then enable its built-in startup option. TUN may require elevated permissions and use a different startup path from a regular login session, so test it by signing out or restarting. For an overview of the main window, tray, logs, and settings, see A Guide to the v2rayN Main Window. Closing the window does not necessarily exit the process.

03 / MACOS

macOS: Choose the Right Chip, Install, and Set Network Permissions

Choose the Package for Your Chip and Install the App

Open About This Mac and check whether your computer has an Apple Silicon chip or an Intel processor. Then go to the macOS downloads section and choose the matching v2rayN package. arm64 and x64 refer to processor architectures, not interface languages or feature tiers. An app launching through a compatibility layer does not prove that you chose the right package. A native architecture match removes extra variables when troubleshooting runtime components and permissions, especially if you plan to use TUN later.

When the download finishes, open the disk image and move the app to a permanent Applications folder using the method provided in the package. Launch it from there. Do not run it long-term from a mounted disk image or move the app directory while it is running. The first launch may trigger checks for the app's origin and permissions. Confirm that the package came from the download option you selected, read the system prompt, and proceed only as allowed by macOS. Disabling system-wide security checks is not an installation step.

If the app will not launch, distinguish an architecture mismatch, unsupported system version, missing runtime component, and a system warning blocking the app. Repeatedly granting permission will not fix the first two, and randomly renaming the app will not fix the latter two. Note the alert text and system details, then check the package requirements. A command to remove extended attributes should not be used as a general fix: it bypasses diagnosis and could target the wrong directory.

Import a Subscription and Check the Active Server

In v2rayN, open subscription group management, add a group, save the full URL, and update it. For the first update, use a regular network connection that is currently working. If the subscription endpoint is reachable only through an existing proxy, confirm that the old connection works before choosing the corresponding update method. Avoid a circular setup where you need the subscription to connect and need a connection to retrieve the subscription. After updating, select a server and set it as current. Check that the core starts before changing system proxy settings.

macOS organizes proxy settings by network service. Wi-Fi, Ethernet, and other network interfaces may each store separate proxy settings, so check the active service after switching networks. The client's automatic configuration needs to apply to the service currently in use. If the browser still connects directly, check the proxy settings in the system network details before changing server parameters. For manual setup, use the local loopback address and the port shown by the client, not the remote server's port.

System Proxy vs. Per-App Settings

Apps that follow the system proxy can usually use the automatically configured endpoint, but tools with their own network settings may ignore it. Terminal tools do not necessarily read proxy settings from desktop network services. For an individual tool, check which proxy types it supports and where its settings apply. Avoid writing temporary test settings to every login session. If it supports SOCKS, check whether DNS resolution happens locally or through the proxy. Different results with the same server can come from different DNS paths rather than a transport failure.

If the browser works but a development tool does not, clear the proxy address previously saved by that tool and compare it with the client's current listening settings. A separately configured proxy will not update when the client's port changes. For connections to local services, preserve loopback and local network access so debugging traffic is not sent through a remote exit. Do not enable unnecessary LAN sharing for convenience: using a proxy locally and providing one to other devices are different deployment tasks.

Using TUN Alongside Other Network Extensions

Enable the client's TUN feature only if you need to route traffic from more apps. macOS may require administrator approval or a helper component, depending on the implementation. After granting permission, check the logs and network status to confirm that the virtual interface was created. If you use a corporate tunnel, network filter, or virtual machine, enable one traffic-routing method at a time and test before checking whether they can coexist. Multiple components changing the default route can create loops or make local network destinations unreachable.

If TUN stops working after waking from sleep or switching between Wi-Fi and Ethernet, try disabling and re-enabling it, then check whether DNS recovered on the current network. Do not change several DNS servers while the tunnel is still active. If system proxy mode still works, temporarily switch back to it to keep a working connection while troubleshooting TUN. Before quitting the app, clear any proxy settings it applied, especially a loopback address left behind after an unexpected exit.

04 / LINUX

Linux: deb, rpm, and Desktop Proxy Settings

Choose the Package Format, Then Resolve Dependencies

For Linux desktops, use v2rayN. Check your distribution and architecture, then open the Linux downloads section and choose deb or rpm. Debian- and Ubuntu-based systems typically use deb; Fedora and openSUSE use rpm packages, though dependency handling varies by distribution. Choose the package architecture that matches your system—using the right format does not guarantee the architecture is correct. Install it with your distribution's graphical package installer or a local package command.

The commands below are for different package management environments; run only the one that matches your system. Open a terminal in the directory containing the installer and replace the filename with the full name of the downloaded file. Installing a local package through the package manager helps resolve dependencies. If installation fails, check the dependency names, architecture, and repository errors rather than forcing the install and risking an unusable app. On openSUSE, use its package management tools instead of copying the Fedora command.

sudo apt install ./downloaded-filename.deb

sudo dnf install ./downloaded-filename.rpm

After installation, launch the app from the desktop application menu. Run graphical apps as a regular user so their configuration is saved in that user's environment. Do not run the entire interface as root just to get it to start; this can create root-owned settings that your regular account cannot write to later. Grant elevated permissions only when the client specifically needs them for a virtual network interface or helper service. A system proxy issue is not automatically a permissions problem.

Importing Subscriptions and Desktop Environment Differences

Add the subscription URL in the subscription group settings, save and update it, then select the server to use. Confirm that the core starts and the logs show no missing files or listener errors before configuring the proxy. GNOME, KDE, and other desktop environments expose proxy settings differently, and apps vary in whether they use them. A client message confirming that system proxy settings were applied only means the operation ran; it does not prove that every process is using the proxy. Test your browser and the specific tools you need separately.

If the browser works but the terminal does not, check the terminal process environment first. The command below only displays common proxy variables; it does not change network settings. Support for variable-name capitalization varies between tools, and an old shell session may still contain a port that is no longer active. To proxy a single command temporarily, prefer that tool's own one-time options. Decide whether to make the setting permanent only after confirming it works, and do not write it directly to a shared environment file for all users.

env | grep -iE '^(http|https|all|no)_proxy='

Desktop proxy settings, environment variables, and app-specific proxy settings are three separate paths. They can point to the same local listener, but they do not sync automatically. Tools that use NO_PROXY may also bypass certain destinations, and matching syntax varies between implementations. If a domain always connects directly, check the tool's own bypass list as well as client routing. Do not keep changing GeoSite rules at the wrong layer.

TUN, DNS Resolvers, and Container Networking

TUN needs access to a virtual network interface and the permissions required to create routes. If it fails to start, check the client log for permission or device errors, then configure any helper component as documented for your package. Do not make the entire installation directory writable by everyone or grant unknown binaries system capabilities. Distribution security policies, service startup methods, and package layouts all affect the outcome. Address the specific error instead of copying privilege commands from another system.

On Linux, DNS may be managed by the network manager, a local resolver, or another component. If enabling TUN breaks domain lookups but a known IP address remains reachable, check the resolution path and client DNS settings. Do not repeatedly overwrite a temporary resolver file as if it were the only source of configuration; it may be regenerated when the network reconnects. Containers, virtual machines, and bridges often manage their own routes and DNS, so preserve access to those subnets before deciding whether to route them through TUN.

Login Startup and Upgrade Rollback

Desktop clients should usually start after the user logs in and the graphical session is ready. Prefer the client's built-in startup option, then check the desktop's startup applications list for duplicates. Starting the same configuration through desktop autostart, a user service, and a system service can cause port conflicts. After enabling startup, confirm that the system proxy is applied to the current session; seeing a process running does not prove that traffic is being routed.

Exit the client and back up its data before upgrading. If possible, keep the same installation source and package format. If the interface works after an upgrade but connections fail, check the core path, configuration compatibility, and rule resources before deleting the user directory. Keep the current logs and compare them with a backup if you need to roll back. For details on installers, desktop launchers, and login startup, see v2rayN on Linux: Installation and Autostart.

05 / ANDROID

Android: Install the Client and Grant VPN Permission

Choose v2rayNG or v2flyNG

Open the Android downloads section. v2rayNG with the Xray core is the recommended option. v2flyNG is an alternative for configurations known to work with the V2Fly core. Do not install multiple clients for the same configuration as your default troubleshooting step. First check whether the current core supports the protocol, transport, and security settings. The two apps manage data separately; installing one does not migrate subscriptions, routing, or permissions from the other.

Most recent mainstream devices use arm64. If you are unsure of the device architecture, consider the universal package listed on the downloads page, but check the device's system information and package notes to confirm. If the system installer reports incompatibility, check the architecture, system requirements, and whether the download completed. If it reports a conflict with an existing app, check that the package source and signature match. Do not uninstall first: doing so may erase private app data, including subscriptions and custom settings.

When installing an app downloaded elsewhere, Android manages permission based on the app that started the installation. Grant only the required permission to the file manager or browser you are using, and revoke it afterward if appropriate. On managed devices, installation or VPN access may be restricted by policy; follow your organization's device management requirements. Do not bypass system restrictions with unknown tools. First determine whether the issue is installation permission, app compatibility, or a device policy.

Add a Subscription, Update It, and Select a Configuration

In the app, open subscription settings or the subscription group screen, add a name and the full URL, save it, then return to the main screen and update. Use the appropriate entry for a remote subscription or a single configuration from the clipboard. After updating, check that configurations appear in the list and select the one you want to connect to. If your provider offers entries for different protocols, follow its instructions. Do not assume the order indicates performance or combine an address and credentials with an unrelated configuration.

QR codes are convenient for importing a single shared configuration, but they may contain credentials. Be mindful of where screenshots are saved and who can access images shared between devices. If a subscription update fails, check the app log to distinguish a failed request, an empty response, and a parsing error. Being able to open your account website in a browser does not mean the subscription endpoint is reachable. It may require the full path and query parameters; omitting part of the URL can return entirely different content.

Understand Android VPN Permission and App Coverage

On the first connection, Android typically uses its system VPN interface to route local traffic through the client. Approve the connection in the system prompt. This creates the local traffic entry point; it does not mean the client has connected successfully to a remote server. After granting permission, check the logs and test access. A VPN icon in the status bar only indicates that the local interface is active. It does not prove that the selected server is reachable or that DNS is resolving as expected.

Android generally allows only one app to use the active VPN connection for a user at a time. If another tunnel app, network filter, or work profile component is already running, check for conflicts before testing. App routing lists also affect which traffic is captured: an allowlist and a bypass list mean different things. Changes may take effect only after reconnecting. If an app still connects directly, check whether it is included in the traffic scope before changing servers or reimporting the subscription.

Background Activity, Network Changes, and DNS

If the connection drops only after the screen locks, check background activity and battery settings. Allow the necessary background activity using your system settings, then test with the screen off and after waking the device. Menu names vary between manufacturers, so do not rely on screenshots from another device. Persistent connections do not require disabling every power-saving feature—change only restrictions that affect the client. If you enable always-on VPN, understand how it interacts with the option to block connections without a VPN so you do not mistake it for a general network failure.

Switching between Wi-Fi and mobile data can change the underlying address, resolver, and network route. Give the app time to reconnect, then check the logs for a specific error. If it fails only on one network, compare that network's sign-in status, DNS, and server reachability instead of deleting all configurations. Android Private DNS, client DNS, and encrypted DNS in individual apps may also interact. Change one resolver at a time and note which change affects the result.

After moving to a new device, check the system VPN permission, background activity settings, and app coverage again; these system settings may not transfer with a configuration file. First verify the default route after migration, then restore custom routing and DNS. For common differences between import and update steps, follow the quick start guide. For other setup and usage questions, visit the Help Center.

06 / CONFIGURATION LAYERS

Subscriptions and Routing: Updates, Rules, and DNS

A Subscription Update Does Not Sync Every Setting

Subscriptions usually distribute server configurations; they do not sync every local preference. System proxy settings, local ports, TUN permissions, and app routing are generally managed on each device. A client may replace or rebuild subscription entries during an update, so do not rely on manual edits inside entries that may be overwritten. If you need persistent changes, use a separate configuration or group if the client supports it, and note why you made them. That makes it easier to tell subscription-provided values from your own changes after the next update.

Subscription updates and server connections may use different network paths. Updating through a proxy can fail if the current proxy is unavailable; a direct update can fail if the subscription endpoint is unreachable on the current network. Choose the update method based on the path that actually works instead of switching repeatedly until one happens to succeed. Compare the groups, entries, and selected server before and after an update to see whether a server was replaced. An unchanged display name does not prove that the underlying address stayed the same.

First Check Whether Traffic Reaches the Core

Routing rules only apply to traffic that has already entered the core. If an app ignores the system proxy, no number of domain rules will automatically route that app through the proxy. Conversely, traffic entering through TUN can still be routed directly by a rule. Traffic capture and remote exit selection are two separate layers. When troubleshooting, confirm the entry point first, then check which route matched, and finally inspect the outbound connection. Mixing these layers can make a working browser look like proof that every other app should work too.

The routing snippet below illustrates how to match private addresses and mainland China domain categories. It is not a complete configuration file and cannot be used as a drop-in replacement for the client's full configuration. Before using it, confirm that the selected core supports these fields, the rule resources are available, and the outbound tags are defined in the active configuration. Clients may use different tag names, so the example will not work on its own. Prefer the client's routing editor and back up your configuration before editing it manually.

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

Rule Order, Resource Files, and the Default Outbound

Many routing implementations evaluate rules in order, so an earlier match can prevent later rules from taking effect. Put specific domain exceptions before broader categories, then check whether the client has added other rules through its presets. The snippet above does not specify what happens to unmatched traffic; determine the default outbound from the complete configuration. Two direct-connection rules do not prove that all other traffic goes through a proxy, and a “global” option in the interface does not override every local app setting.

geosite:cn depends on domain classification data, while geoip:private requires support for the corresponding IP classification. Domain rules need domain information to match; IP rules are based on the destination address. They are not interchangeable. A missing rule database or undefined tag can prevent the core from starting, and database updates can change routing results. After updating the client, check the resource-loading logs as well. For details, see How to Update GeoIP and GeoSite Rule Databases.

DNS and Core Switching Boundaries

DNS routing and connection routing need to work together, but they are not the same setting. Sending a domain through a direct outbound does not mean its DNS query uses the local resolver; a remote DNS server also needs a reachable network path. FakeDNS adds virtual address mapping and traffic-capture considerations, so do not copy a toggle from another configuration without understanding it. First verify the connection with standard DNS, then introduce routing gradually. For configuration details, see A Guide to V2Ray DNS Split Routing and check the fields supported by your current core.

When switching between Xray and V2Fly, recheck the protocol, transport, security settings, and configuration generated by the client. A selectable option does not mean every combination is compatible. Keep the original configuration and logs before switching. Afterward, confirm that the core starts, then test a destination that worked before. Do not change the core, DNS, routing, and server at the same time; otherwise, you will not know which change affected the result.

07 / DIAGNOSTICS

Common Configuration Issues: Troubleshoot from Startup to Connection

Note What Happened Before Choosing What to Check

A useful issue report includes the platform, client, traffic-capture mode, action taken, and error type. Break “it won't connect” down into a specific problem: the app will not open, the core will not start, a subscription update fails, the browser cannot connect, or only one app fails. This makes it possible to choose the right troubleshooting path. Keep a copy of the current configuration instead of clearing data immediately. Check logs around the time the problem occurred; an old startup error may have nothing to do with a later failed request. Do not jump to conclusions based on one conspicuous error message.

Use a consistent troubleshooting order: local network, client process, core startup, local listener, server connection, DNS resolution, and app traffic capture. Test one issue at each layer and record the result. A known working website can help compare before and after, but one site's availability does not prove that all connections work. The site itself, account restrictions, or app cache can affect the result. The goal is to narrow down the cause, not to keep changing settings until something works temporarily.