Client Installation Handbook
Complete V2Ray Setup Guide
Find installation steps by platform and troubleshoot connections layer by layer. Covers subscription import, system proxy and TUN mode.
Setting things up for the first time? Follow the quick-start guide to import a configuration, choose a mode and verify the connection. This page is a reference: jump to your platform if you’re unsure which package to install. If a node connects but apps aren’t using the proxy, start with connection checks or troubleshooting.
Before You Install: Clients, Packages and Subscriptions
Client, core and node: what’s the difference?
The client is the graphical app you use day to day. It stores subscriptions, lets you choose nodes and switch proxy modes. The core reads the configuration in the background, establishes connections and applies routing rules. A node is a remote connection profile, usually containing a server address, port, authentication details and transport settings. Installing and opening a client doesn’t give you a working node, and importing a node doesn’t mean your apps are using the proxy.
Project V is a useful starting point for understanding this ecosystem. V2Fly continues the community development of V2Ray, while Xray is another core that grew out of the same ecosystem. Protocols with the same name may not support exactly the same transports or security options across different cores. Before migrating, check which core and transport combination the original configuration uses, then confirm the target client can read it. Matching node names alone don’t make two configurations equivalent.
Check your OS before choosing a package
For desktop, start with v2rayN. On Android, v2rayNG with the Xray core is the usual choice; consider v2flyNG if an existing configuration specifically requires the V2Fly core. Check your device’s OS and processor details before opening the download page. Similar-looking computers can use different architectures, and the same architecture may still require different package formats depending on the OS or distribution.
| Platform | Client | What to check |
|---|---|---|
| Windows | v2rayN | System architecture; Desktop or WPF interface |
| macOS | v2rayN | Apple silicon or Intel processor |
| Linux | v2rayN | Distribution package format; x64 or arm64 |
| Android | v2rayNG; v2flyNG as an alternative | Core requirements; arm64 or universal package |
Architecture labels describe the system environments a package can run on, not its speed. Even if a phone’s processor supports 64-bit apps, the OS may not provide a compatible runtime. On desktop, distinguish an installer from a portable archive: installers typically set up the app directory and shortcuts, while portable builds need their extracted directory structure intact. Before switching packages, check what kind you have. Don’t copy an executable by itself from an old folder into a new one.
Subscription URLs and single-node links
A subscription URL usually looks like a web address. The client uses it to retrieve a list of nodes. Adding the URL creates a subscription group; update it to fetch the nodes. Links starting with vless:// or vmess:// usually describe one node and should be imported with the client’s clipboard import option. A web address might also lead to a login or help page. Check what it’s for instead of assuming any web link is a subscription.
QR codes also need a quick check: do they contain a single node or a subscription? After scanning, see whether the client opens an add-subscription form or a node preview. If a group with the same name already exists, check the new entry by group and node type; there’s no need to clear the list just to confirm the import. For details on how different links update, see share links vs. subscription URLs.
Keep a way to restore your original settings
Before installing, note whether the system proxy is enabled, whether you use another VPN, and whether your work environment requires a specific proxy. Don’t overwrite settings managed by your organization. If you already have a client, use its backup or export feature to save your configuration first. Preserve subscription groups, manually added nodes and custom routes before considering a move to another client. Treat exports as sensitive data; on shared computers, don’t leave them in a public Downloads folder.
For your first test, keep the process simple: import one node or subscription, select one node, enable one traffic-routing method and visit a test destination you’ve chosen in advance. Don’t change DNS, routing rules and startup settings all at once. Add those later, once the connection works. If the first attempt fails, fewer changes make it easier to tell whether the problem is installation, import, core startup or app traffic routing.
Windows: Install v2rayN and Set Up the System Proxy
Choose the Desktop or WPF package
Open Settings → System → About and check your system type. Then check the package details in the Windows downloads. Desktop uses a cross-platform interface; the classic WPF edition keeps the familiar Windows layout. Choose based on system compatibility and preference, not the node protocol. The x64 download is for x64 systems. If your device uses another architecture, confirm that Windows supports a compatible runtime before downloading; the bitness in a package name isn’t a compatibility guarantee.
Close the old client first, including any instance still running in the system tray, then run the installer. Follow the setup wizard and launch the app from the new shortcut. If it reports a missing runtime, note the component name and architecture before following the package instructions. If Windows blocks the app, check the download source, system warning and device management policy. Don’t disable system protections to get it running or use a system folder to store configuration files.
Import a subscription and select a node
Use the subscription menu to add a group. Enter a recognizable label and the full subscription URL, then update it. If your computer doesn’t have a working proxy yet, try updating without one; this only works if your current network can reach the subscription service directly. If the URL is accessible only through an existing connection, get that connection working first, then update through the proxy. Don’t rely on an “update successful” message alone—open the group and confirm that its nodes appear.
If you only have a share link, copy the entire link and use the clipboard import option. Select the imported entry and set it as the current server or active node; the exact label depends on the interface. A highlighted row isn’t necessarily the node in use. Check the client status or logs for the current connection instead of trying every duplicate entry one by one.
Use the system proxy for browsers; use TUN when needed
From the system tray menu, set the system proxy to “Set system proxy” or the equivalent option, then make a new request in a browser that uses the system proxy. This setting tells apps where the local proxy is; it doesn’t route all processes automatically. Tools with their own network settings may still connect directly, and browser extensions, managed policies or custom proxy settings can override the system setting. If an app lets you set a proxy manually, test it on its own first. You don’t have to change how the whole computer routes traffic.
Test TUN separately if an app needs to be routed through a virtual network interface. Note the original mode first, disable any manual proxy in the test app and follow the client’s instructions for permissions. After enabling TUN, confirm that the virtual interface and related routes are in place. Then test regular browsing, local network access and any work connections that must remain available. An enabled TUN switch doesn’t guarantee routes were installed. If it fails, turn TUN off and check the startup error instead of repeatedly granting permissions or restarting.
Check for leftover tray processes and port conflicts
v2rayN may keep running in the system tray after you close its main window. Before upgrading or switching between Desktop and WPF, choose Exit in the old instance, then open the new version. If the log says a local port can’t be bound, check which port the error refers to and whether an old client or another local service is listening on it. Don’t terminate processes you don’t recognize. If you need to change the port, update any manual proxy address saved in your browser or other apps too.
If the internet stops working after you quit the client, check whether the system proxy still points to a local address and whether anything is still listening on that port. This can look like a full internet outage when apps are actually trying to reach a local proxy that has already closed. If only one app won’t recover, reopen it and test again; it may still be using an old connection. Once local settings are restored, check whether the remote node or network has a separate issue.
macOS: Choose the right build, install the app and configure the proxy
Choose a disk image based on “About This Mac”
Open “About This Mac” from the Apple menu. If the device details show Apple silicon, choose the arm64 build in the macOS downloads. If they show an Intel processor, choose x64. Use the system information rather than terminal output from an emulated environment to identify the chip. If you’re unsure, don’t install both packages to see which works; two copies of the same app can make launch paths and proxy status harder to track.
Open the downloaded disk image and drag the app into Applications as instructed. Launch it from that folder, then eject the disk image. Don’t run the app from the disk image long-term or keep two copies with the same name in Downloads and Applications. Before replacing an old copy, quit it completely from the menu bar or app menu. If macOS won’t open the app, check whether the issue is an incompatible architecture, OS version or management restriction. Don’t disable app security across the board.
Organize subscriptions into groups and check permissions
Open v2rayN and add a group in the subscription menu. Paste the full URL, give the group a recognizable name and update it manually. If you use multiple desktop spaces or app windows, check that the current window shows the new group rather than all nodes. If you only have a share link, import it from the clipboard into a clearly named local group. That makes it easier to distinguish entries updated from a subscription from those you maintain manually.
To move subscriptions from an old computer, recreate groups with their original subscription URLs, then import only the manually added nodes you want to keep. Avoid replacing the entire app configuration directory: local paths, ports, permissions and core options from the old system may not suit the new device. If the app asks for permission on first launch, check whether it involves network routing or local file access. Grant only what the current task requires and note what changes afterward.
Check the system proxy for each network service
After enabling the system proxy in the client, open System Settings → Network and check the proxy settings for the active network service. Wi-Fi and Ethernet may use different services, and their proxy settings may not match. If you see a loopback address, confirm that its port matches the local listener shown by the client. An old port can remain in System Settings but won’t receive requests for the new process.
If only one app can’t connect, first check whether it uses the system proxy before switching to TUN. If the current build supports TUN, follow the interface steps to enable it, stop any conflicting local proxy and test a regular webpage, local network access and the connection after waking from sleep. If the client reports a permission or routing error, go back to the system proxy to verify the basic connection. Repeatedly toggling the setting won’t identify the cause.
Handle wake-from-sleep issues, network changes and leftover proxy settings
A network device may close old connections while the computer sleeps, and after waking, the computer may be connected through a different network service. If a page hangs, first check that the current network is online, then reconnect with the client and make a new request. Old tabs, long downloads and background sync may keep trying to use an old connection; that doesn’t mean new requests will fail too. If the problem keeps recurring, note whether it happens only after switching networks or waking from sleep.
If local network access still fails after clearing the client’s system proxy, check whether the active network service has a proxy script, manual proxy or special exclusions, and whether another network tool is still running. Keep settings managed by your organization. Only revert settings added during this setup, using your original notes. After restoring them, test a local service before the internet. If local access fails, investigate the local network path rather than switching remote nodes.
Linux: Package formats, desktop proxy and TUN
Match the distribution and architecture
Choose v2rayN in the Linux downloads. Debian-based distributions usually use deb packages; Fedora and other distributions using the RPM package system use rpm. Matching the format is only the first step—also check the distribution version, dependencies and desktop environment. These aren’t just two file extensions, so don’t use a conversion tool to force-install the wrong format. If you only have a terminal, use the read-only commands below to identify your system.
cat /etc/os-release
uname -m
/etc/os-release provides distribution details, while uname -m shows the machine architecture seen by the current kernel. Common outputs are x86_64 for x64 and aarch64 for arm64. If you’re working in a container, virtual machine or mixed-architecture environment, also check the architecture used by the package manager on the actual installation target. On Debian-based systems, for example, run dpkg --print-architecture. Don’t use the host system’s result for the guest.
Launch from your current desktop session, then import a subscription
Open the compatible local package with your system’s software installer, review any dependency warnings and complete the installation. If installation fails, check for a missing package, architecture conflict or distribution version restriction. If installation finishes but no window appears, try launching the app from the application menu and make sure you’re in an active graphical session. Launching a graphical app from a remote terminal may not use the same display or proxy settings as launching it from the logged-in desktop.
Once the app opens, create a group in the subscription menu and update it. Confirm the nodes appear; import a single share link from the clipboard. Run the app as your regular desktop user. Starting it with administrator privileges just to get the interface open may save configuration under a different user directory, making it look like your data disappeared when you return to your normal account. For network features that need elevated permissions, use the authorization method supported by the client rather than running the entire graphical app with elevated privileges.
Test desktop proxy and terminal proxy separately
A desktop environment’s system proxy is a setting that apps can choose to read; not every desktop or application uses the same interface. Browsers may follow the desktop setting, while terminal commands may require their own options or environment variables. First confirm that the client’s local HTTP or mixed proxy is listening, then specify it for a single command. That way, you can test a connection without adding proxy settings to shell startup files. The example prompts for the local HTTP or mixed proxy port shown in the client.
printf 'Local HTTP or mixed proxy port: '
read -r proxy_port
curl --noproxy '' --proxy "http://127.0.0.1:${proxy_port}" \
--max-time 15 --head https://example.com/
This command works when the local proxy accepts HTTP connections on the loopback address. If the settings show a SOCKS-only listener, use the corresponding protocol option instead of entering its port here. If the explicit proxy request succeeds but regular apps still fail, check how those apps route traffic and whether they have their own proxy settings. A response from the destination only proves that this request had a working path. Compare it with the client’s routing logs to confirm whether it used a remote node.
Check permissions, interfaces and existing settings before using TUN
Before enabling TUN, make sure the environment supports virtual network interfaces and the current build supports TUN mode. Containers and managed environments may allow the client to open without allowing it to create an interface or change routes. If the client reports a permission or interface error, return to the verified system proxy and check which permissions your environment allows. Don’t blindly copy commands that change system capabilities or start troubleshooting by disabling the firewall.
If TUN starts successfully but a terminal or service still behaves unexpectedly, check whether it has old proxy environment variables or runs in its own network namespace. After turning TUN off, test again in a new terminal and a new browser window. If new sessions work but old ones don’t, the process may have inherited stale environment settings. If apps across the same desktop are affected, check whether interfaces, routes and DNS settings returned to their expected state.
Android: Install v2rayNG and route traffic through VPN
Choose a client and package for your needs
Open the Android downloads. For typical use, start with v2rayNG, which uses the Xray core. Consider v2flyNG if a configuration specifically requires the V2Fly core. Choose the arm64 package if your device supports arm64 apps. If you’re unsure which app architectures the system supports, consider the universal package for the same client. A universal package supports more architectures, but doesn’t remove OS version restrictions or fix a signing conflict with an existing app.
When the download finishes, open the package from your file manager or browser. Follow the system prompt to grant the necessary permission to install from that source; you can revoke it afterward. For updates, use a package from the same publisher or distribution source as the installed app. If Android won’t install over the existing version, check whether the signature differs, the version can’t replace the installed one, storage is low or a device policy is blocking it. Don’t uninstall the old app right away; that may delete subscriptions, manually added nodes and per-app settings. Back up anything you need first.
Add a subscription or scan a single-node QR code
Open the client and add an entry in the subscription group settings. Enter a label and URL, save it, return to the node list and update the subscription. When the update finishes, make sure you’re viewing the right group so old nodes from another group don’t mislead you. For the first import, keep the default configuration and select one node as a baseline. If the URL updates on desktop but not on your phone, note whether the phone is on Wi-Fi or mobile data. Don’t delete the subscription that already works on desktop.
For a single-node link, copy it and use clipboard import. For a QR code, use the client’s scan or image import option. Like configuration text, a QR code may contain credentials, so don’t leave it in a shared photo library. If it won’t scan, check whether the image is cropped, compressed or reflective, then confirm what the code is for. Updating a subscription group and scanning a node are separate actions; scanning a node doesn’t automatically create a subscription for it.
Understand VPN permission and app coverage
Select a node and start the connection. The system usually shows a VPN connection confirmation. This allows the client to route specified traffic, unlike entering a system proxy address on a computer. After confirming, check the client status and the system VPN indicator, then make a new browser request. The indicator means the routing service is running; it doesn’t guarantee the remote node works or that every app is covered. If the indicator appears and disappears immediately, check whether another VPN or system policy replaced the service.
If the client offers per-app proxying, treat it as a setting for which apps are covered, not as a way to choose a node. Check whether the interface includes only selected apps or excludes them, then configure it accordingly. Having a browser on the list doesn’t mean a download manager or a separately launched app is included. For troubleshooting, choose a clear coverage setting and test with one browser first. Once it works, add your original app list back. Always-on VPN or blocking connections outside the VPN can affect rollback tests, so note those settings before changing them.
Distinguish network changes, background restrictions and device policies
If the connection drops only after the screen turns off, check whether the VPN service is still running when you wake the device. Then check for background restrictions or battery-saving policies. Adjust the app’s permissions in system settings only if the issue keeps happening and affects your use. You don’t need to disable battery protection for the whole device. If the connection is active but won’t switch to mobile data, turn off the old connection and reconnect once. Use a new request to determine whether the connection needs to be restored or the current network is unreachable.
On devices managed by a school, employer or other organization, system policies may restrict installation, background activity or VPN use. Those restrictions aren’t related to whether the subscription is valid; follow the device management requirements. If you’ve switched between Wi-Fi and mobile data but only one app fails on both, check the per-app list, the app’s proxy settings and routing rules. If the VPN service itself won’t start, resolve local authorization or conflicts with another VPN before checking the node.
Verify a connection: from local listening to route match
Break a connection test into four checks
First, check whether the core starts. On desktop, look for the local proxy port to begin listening; on mobile, check that the system routing service starts. Second, check whether the test app’s request reaches the client: make a new request and watch the logs. Don’t rely only on the connection button or a node list test. If the client receives no request, changing remote nodes probably won’t help; check how the app’s traffic is routed first.
Third, check which routing rule matched the request and whether it was proxied, sent directly or blocked. Fourth, check whether the destination responds. A webpage may load from multiple domains, and its main document, images, scripts and login endpoint may follow different rules. Start with a test destination that makes requests easy to identify and doesn’t depend on a collection of third-party sites, then return to the original app. Choose a destination relevant to normal use, but don’t use your account page or actual subscription URL as a demonstration.
| Stage | What you can observe | Check first |
|---|---|---|
| Startup | Core exited or interface not created | Configuration, port, permissions |
| Traffic routing | No request from the test app in the logs | Log level, proxy mode, app coverage |
| Routing | Request received but sent through the wrong route | Match conditions, rule order, default outbound |
| Outbound connection | Expected outbound selected, but no response | Node connectivity, DNS, transport and security settings |
System proxy, global routing and TUN are different
“System proxy” describes how an app finds the local proxy. “Global” usually describes which outbound route client traffic uses. They aren’t the same setting. Even with global routing enabled, a process that doesn’t use the system proxy may never send traffic to the client. TUN routes traffic through a system virtual network interface when it matches the routing conditions. Its coverage is usually broader, but it can still be limited by exclusion rules, system capabilities or other network services.
For your first test, don’t change all three at once. Follow the system proxy setup steps to test an app that you know uses the proxy. Then decide whether TUN is needed for your actual use. When switching modes, restore the previous routing method to its expected state first. Otherwise, an app may keep using an old port after the virtual interface is enabled. Keep the same node, destination and network for both tests and change only the routing method to make the results comparable.
Check rule order, domains and IP addresses
Use the interface to check routing rules and the default outbound. In an ordered list, the first matching rule usually applies. A broad condition near the top may catch a request before a more specific rule further down. Whether a rule sends traffic directly or through a proxy also depends on its assigned outbound. Don’t start by deleting everything. First check which condition matches a clearly identifiable test request, then adjust the rule that actually affects it.
Domain rules organize traffic by hostname; IP rules apply to specific addresses or ranges. Whether a hostname is available, and whether it’s resolved before matching, depends on the app’s destination and the core’s settings. A domain and a direct connection to its IP may not match the same rule. If only some sites are affected, check the actual request destination rather than the browser tab title. Export the current routes before editing rules so you can restore their original order.
Keep databases, DNS and node updates separate
GeoSite contains domain categories; GeoIP contains IP address categories. Rules using these categories depend on the databases loaded by the core and on the rules themselves. Updating databases and updating subscriptions are separate operations: the former changes data used for rule matching, while the latter refreshes the node list. If a rule is still present but its category isn’t found, check that the correct database set is in use and that the current core can read it. Don’t drop updated data files into an arbitrary old directory.
If a domain won’t resolve, you don’t need to immediately change all your DNS settings. First identify whether the failure is with the subscription service, node server or test destination, then check whether it occurs in the app, system or core. Some apps use their own DNS resolution, so working system DNS doesn’t prove the app’s DNS is working. Record what happens, change one setting and test again. For details on routing data formats, see the GeoIP and GeoSite database update guide.
Common Setup Issues and How to Fix Them
Start with the most recent change
Work backward from the last time everything worked. Did you update the client, replace the core, change a subscription, switch Wi-Fi networks or adjust the system proxy? Record the time of the last change separately from when the problem first appeared. If possible, undo the most recent change first and retest with the original node and destination. If you uninstall, change DNS and reset routes all at once, even a successful fix won’t tell you what to do next time.
Choose a troubleshooting path by symptom
Subscription update failed: check the URL or the node first?
Start with the subscription URL and how it’s being fetched. Check that the original URL is complete, especially for spaces, line breaks or trailing punctuation added when copying. A login page, error page or empty response can download successfully but still fail to parse as a configuration. Use the client’s error details to tell whether the request didn’t reach the server, access was denied or the content format was wrong. Then consider changing the update route.
If the old group still has nodes, keep it. A working old node doesn’t mean the subscription can still update, and a failed update doesn’t mean every existing node is broken. Updating without a proxy only helps if your current network can reach the subscription service directly. If you need an existing connection, use a working node to restore the proxy before trying again. If both routes are denied, check the URL’s validity and access requirements. Don’t keep pasting the URL or share it publicly to ask for help.
The node imported, but why won’t it connect?
Make sure it’s selected as the current node and that the client has started the connection. If the core exits on startup, use the error to check configuration fields, file paths or local ports. If it only times out when an app makes a request, check node address resolution, remote port connectivity and handshake errors. A node list test and an actual app request may take different routes, so don’t treat the test icon as conclusive.
If only one node reports a handshake error, check the protocol, transport, security settings and server name in the source configuration, and make sure the system clock is accurate. Changing the port or ignoring certificate errors won’t confirm the cause and may make it harder to diagnose. If another node in the same subscription works on the same network and in the same mode, keep it as a comparison and investigate the failing node on its own. There’s no need to reinstall the client.
Why does the browser work when other apps don’t?
Check whether the failing app uses the system proxy or has its own proxy settings. Desktop apps can use separate network settings, and terminal sessions may retain environment variables from an earlier session. On mobile, also check whether the app is excluded from VPN coverage. Quit the app completely, make a new request and watch to see whether the client receives it.
If the logs show the request, check the matched route and destination response. If there’s no record, check the log level and then the traffic coverage settings. If the app supports its own proxy setting, test with the local address first; you can undo the change afterward. Switch to TUN only if needed, and keep the original settings so you can restore them. One app failing doesn’t mean the system proxy is wrong, and there’s no need to move working apps to another mode.
How do I restore groups and routes after an upgrade or device change?
Open the backup and sort its contents into three groups: nodes that can be fetched again from subscriptions, manually saved links and device-specific inbound and routing settings. Start with the smallest configuration that passes a connection test, then migrate one part at a time. Recreate subscription groups from their original URLs and import manual nodes individually. Reconfigure local ports, virtual interfaces and core-specific routes for the current device.
Don’t overwrite a different client’s configuration with the entire old configuration directory. Even if both clients can read some nodes, they may handle default outbounds, app lists and data file paths differently. If you have several subscriptions, organize them by source first, then use the subscription groups and node filtering guide to remove duplicates. Once everything works, keep a backup that starts successfully before removing the old configuration.
Restore local settings if the internet stops working after you quit
If the client has quit but no browser can connect, check whether the proxy still points to a local port. Revert only settings written during this session and restore the previous manual proxy, automatic configuration script or direct connection setting. On a device that used TUN, check whether an old process still owns the virtual interface. On Android, check whether the system still shows a VPN connection and whether blocking connections outside the VPN is enabled or controlled by a device administrator.
After restoring settings, test two separate destinations: a local service that normally works and a reliable internet destination. Confirm the network is back before reopening the client. If devices on multiple platforms fail on the same network but work on another, record the results from before and after switching networks. Don’t start by blaming every device’s installation package. When asking for help, include the platform and architecture, client and interface type, routing method, error type and tests you’ve already run. Don’t post full logs.