Client Manual / Complete Setup Guide

Complete V2Ray Setup Guide

Setting things up for the first time? Follow the Getting Started guide to import a subscription, connect, and verify it works. This page is a reference manual: jump to the section for your operating system or troubleshoot by symptom—there’s no need to reinstall just to identify a problem.

Before you begin: packages, subscriptions, and permissions

Identify your operating system, processor, and package format

Choose a package by first checking your operating system, then its reported processor architecture, and finally the package format. For desktop systems, v2rayN is the recommended choice. On Android, start with v2rayNG, which uses the Xray core; consider v2flyNG if you specifically need the V2Fly core. Similar client names don’t mean their packages are interchangeable—or that every configuration in an imported subscription will work. Still comparing options? See the client comparison. If you already know your OS and architecture, go straight to the download page.

Operating systemClientPackage to chooseFirst test
Windowsv2rayNx64 desktop or classic WPF editionSystem proxy and browser
macOSv2rayNDMG for Apple Silicon or IntelProxy settings for the active network service
Linuxv2rayNx64 or arm64; choose DEB or RPM for your distributionA request sent to the specified local proxy port
Androidv2rayNG、v2flyNGarm64 or universal APKSystem VPN status and app access

A 64-bit operating system doesn’t necessarily mean the processor is x64: arm64 is also 64-bit, but uses a different instruction set. Package formats can’t be made interchangeable by changing a file extension, either. DEB and RPM packages are handled by different package managers and include different dependencies and installation records. If the download page doesn’t list a package for your device’s architecture or format, check the client’s supported platforms first. Don’t try to force an installation by repeatedly renaming the file, switching archive tools, or overriding safeguards.

Understand subscription URLs, individual configs, and the active node

A subscription URL retrieves a set of configurations; a single share link describes one connection. Import each from the appropriate menu. On desktop, you’ll usually save the URL under “Subscription Group Settings,” then go to “Subscription Group” in the main window and update it. Importing a single share link from the clipboard doesn’t replace these steps. Once the list appears, select a configuration to make it active. Give subscription groups easy-to-recognize names, perhaps by purpose, but don’t put URLs, account identifiers, or node passwords in the group name.

Subscription URLs may contain access credentials, so treat them as private links. Don’t paste them into public notes, online conversion tools, or support posts. When asking for help, explain which step failed and share only relevant log lines with URLs, credentials, and device identifiers removed. To migrate from an old device, use the client’s supported export and import options where possible. Exported configuration files may contain credentials, so store them carefully. Don’t replace an entire old installation directory with a new version—especially don’t carry over old cores or caches.

Start your first test with a clear baseline

Before you begin, check whether ordinary websites load with the proxy off, whether the device’s date, time, and time zone are correct, and whether other proxies, network filters, or VPNs are running. Work-managed devices may have a fixed proxy or managed network policy; change settings only when authorized, and note their original values. For the first connection, consider disabling this client’s automatic updates and launch-at-login so it won’t change test conditions when you switch networks or restart. Record the current network, the app you’ll test, and the expected result to make comparisons easier.

On desktop, a system proxy tells apps that honor the setting to send requests to the client’s local endpoint. TUN uses a virtual network interface to receive traffic covered by the relevant routes, and generally handles more traffic. Android uses the system VPN interface; you don’t need to enter a desktop proxy address in the Wi-Fi settings. Neither method automatically covers every app and request. For your first test, define a specific goal—such as “open a test page in the browser”—rather than assuming the whole device is covered.

Windows: Install v2rayN and configure the system proxy

Confirm x64, then choose the desktop or WPF edition

Open Windows Settings → System → About and check “System type” under Device specifications. You can also search the Start menu for “About your PC.” Once you’ve confirmed an x64-based processor, choose v2rayN from the Windows download options. The desktop edition uses a cross-platform interface; the classic WPF edition keeps the familiar Windows layout. They don’t use different connection protocols. If you’re new to the client, choose either one. If you’re migrating from an older version, compare the desktop and WPF editions before deciding whether to keep the old installation.

After downloading, follow the installer. On first launch, make sure you’re opening the newly installed copy, especially if an older shortcut is pinned to the taskbar. If the client reports a missing runtime component, install the component required by your selected edition and relaunch. Don’t try to fill the gap with program files from another edition. If the client appears only in the system tray, open the hidden icons area at the right of the taskbar and look for its main window; repeatedly double-clicking may make it seem as though the client hasn’t started. Before upgrading, exit the old instance so two processes don’t compete for the same listening port.

Import a subscription and test with just the browser

In the main window, open “Subscription Group → Subscription Group Settings,” add a group, and enter the subscription URL. Save it, return to “Subscription Group,” and first choose “Update all subscriptions (without proxy)” or a similarly named option. If you don’t have a working connection yet, don’t rely on updating through the proxy: the client may need a connection before it can retrieve the configuration. When the update finishes, confirm the nodes appear in the expected group. Right-click one, select “Set as active server,” then check the status bar or logs to confirm the change. Menu wording can vary by version, but saving the URL, updating the list, and choosing an active item are separate steps.

From the system tray menu, choose “System Proxy → Set system proxy.” Open a test page in a browser that uses the system settings by default. If needed, check Windows Settings → Network & Internet → Proxy to see whether a system proxy is set, and compare it with the client’s local endpoint. Note that Windows “Automatically detect settings” is not the same as v2rayN’s “Set system proxy”: the Windows option looks for a network proxy configuration. If your browser has its own proxy extension or policy, check whether it overrides the system setting, then retest in a browser window without that override.

Enable TUN only if you need broader traffic coverage

If the browser connects but a desktop app ignores the system proxy, check the app’s own proxy settings before deciding whether to use TUN. First, select “Clear system proxy” in v2rayN’s system proxy menu. Then grant any permissions the client requires and enable “Tun” in the main window. If you see an error about creating the interface, insufficient permissions, or adding routes, save the logs and check whether another VPN or virtual networking tool is using the same settings. On managed devices, don’t disable endpoint protection or change managed policies just to pass a test; confirm what’s permitted first.

If you don’t need TUN, the system proxy is usually easier to undo for everyday use. Some background services and command-line tools use their own proxy settings, so a working browser doesn’t prove they follow the same route. If the client reports an address conflict on startup, use the logs to identify the local port in conflict and check whether an old instance is still running. If you change the port, update any apps you configured manually. Before exiting, select “Clear system proxy,” then quit the client from the tray. If your network had a work or personal proxy configured manually, restore the values you noted earlier instead of leaving the system settings blank.

If a local proxy address reappears after your next sign-in, check whether both an old and new version are registered to launch, and whether a work policy is automatically restoring the setting. For a retest, keep only one client instance running and confirm the local listener is up before opening the browser. If ordinary websites work when the client is closed but consistently fail when it’s open, check the imported configuration, active node, and handshake logs. If they still fail with the client closed, first check Windows proxy settings and network connectivity.

macOS: Install v2rayN and switch network services

Download the DMG for your chip, then move the app to Applications

Open “About This Mac” from the Apple menu. If it lists a “Chip” and says Apple silicon, choose the arm64 package for Apple Silicon. If it lists a “Processor” and says Intel, choose the x64 package for Intel. Get the matching DMG from the macOS download options. Open the disk image, follow its instructions to move the app to Applications, eject the image, then launch the app from Applications. Running the app directly from the mounted image may leave you without a working launch path after you eject it.

On first launch, distinguish a notice about the download source from a launch block or a system compatibility warning. Only proceed through the system’s confirmation flow if you trust the source and your device policy permits it. Don’t disable system protections globally for one app. If the app can’t run on your current system, check the chip type and app requirements instead of repeatedly trying to open it with elevated privileges. Before updating, quit the old instance, replace the app, and keep a separate backup of your configuration; the app itself and your personal settings are different things.

Import a subscription and check the active network service

In v2rayN’s main window, open “Subscription Group Settings” and add the URL. Return to “Subscription Group” and update without using the proxy. Once the list appears, select an active configuration and check the logs for repeated parsing or connection errors. Then open the client’s menu bar icon, choose “System Proxy,” and select “Set system proxy.” Go to System Settings → Network and open the network service you’re using. For Wi-Fi, for example, open Wi-Fi → Details → Proxies and check that the relevant proxy’s server and port match the client’s settings. Labels may vary between macOS versions; make sure you’re checking the details for the active service.

System proxy settings are associated with a network service. If you switch from Wi-Fi to Ethernet or connect a dock, settings on the previous service may not apply to the new connection. The client may still appear active in the menu bar even though the browser is using different settings. First check which service is carrying traffic, then inspect its proxy settings. Don’t keep toggling the old Wi-Fi service. If the device already has an automatic proxy configuration script, note what it’s for. When manual proxy settings and automatic configuration are both present, an app’s behavior may depend on how it reads system settings.

TUN and recovery after waking from sleep

Try “Enable Tun” only if you need to handle apps that don’t read the system proxy. First remove the system proxy you set for this test, then grant any required permissions and check the logs to confirm that the virtual interface and routes are active. The button’s state only confirms that the client received the toggle—it doesn’t prove the setup succeeded. If your build doesn’t offer this feature or device management prevents route changes, use the system proxy or the app’s own proxy settings. Don’t blindly change the default route with system-level commands.

After waking from sleep, the system may reconnect to Wi-Fi before restoring app connections. If traffic briefly stops, first confirm the network service is back, then open a new webpage. Don’t repeatedly refresh the subscription before the network has an address. If the problem persists, note whether the access point changed during sleep, check that the client’s local listener is still running, then reset the system proxy or re-enable TUN according to the mode you’re using. If the Wi-Fi network requires a sign-in page, temporarily disable the proxy you set for this test, sign in, and reconnect after confirming basic access works.

When you’re done, clear the system proxy from the menu bar or disable TUN if it’s enabled, then quit the client and recheck the active network service. If the service had a custom proxy before testing, restore only the values you recorded; don’t delete settings for other services. For intermittent wake issues, note whether the problem affects just one service or happens after every wake. That distinction helps tell a network-switching issue from a client or app connection that failed to recover with the system.

Linux: v2rayN packages, desktop proxy, and TUN

Choose DEB or RPM based on your architecture and distribution

In a terminal, run uname -m. The common output x86_64 corresponds to x64 on the download page, and aarch64 corresponds to arm64. Then check /etc/os-release to identify your distribution and default package manager. Debian- and Ubuntu-based distributions usually use DEB; Fedora and other distributions using DNF use RPM. Don’t choose based on the desktop’s appearance: the same desktop environment can run on many distributions. Choose v2rayN from the Linux download options, confirm the architecture and format, then open the package manager.

If you prefer a graphical interface, open the downloaded package with your distribution’s software installer. If installation fails because dependencies can’t be satisfied, first confirm that your software repositories are available and the package matches your distribution, then check which dependency is missing. Don’t force the installation while ignoring dependencies: a missing component might not cause an error until launch, tray display, saving settings, or switching proxies. After installation, launch the client from the desktop app menu and configure subscriptions and proxy settings as your usual user. Don’t use administrator privileges for routine launches.

Some desktop environments don’t show a traditional tray icon on the main panel. If the client disappears after you close its window, first check whether it was minimized to the tray, then try reopening it from the app menu. If you have multiple user sessions, make sure the client is running in the session you’re using. If you previously launched it as an administrator and now can’t save settings as a regular user, don’t keep using administrator mode to hide the problem. Back up your configuration, confirm which client directory has the wrong ownership, and restore it using your distribution’s supported method. Don’t recursively change ownership across your entire home directory.

Import a subscription and distinguish desktop from terminal proxies

Add a group and save the URL in “Subscription Group Settings,” then select “Update all subscriptions (without proxy).” Once the list appears, choose an active configuration. Whether “Set system proxy” can configure the desktop proxy depends on the desktop environment and the client’s integration. Check the actual settings under Network → Network Proxy in your desktop settings; some environments put the option under System Settings → Network → Proxy. Even with the desktop proxy enabled, terminal tools may require their own options or environment variables, so test them separately.

The command below uses a local HTTP proxy for this request only; it won’t change your desktop or persistent terminal settings. Before running it, replace the example port with the HTTP port shown in v2rayN, or confirm that the mixed inbound port supports HTTP. Don’t put a SOCKS-only port after http://. curl must be installed locally, and you can replace the URL at the end with a webpage you’re allowed to test.

uname -m
cat /etc/os-release
curl --max-time 15 --noproxy '' \
  --proxy http://127.0.0.1:10809 \
  --head https://example.com/

If you immediately get a connection error to the loopback address, check that the client is listening and that you copied the right port. If the local port connects but the request then times out or returns a proxy or TLS error, check the active configuration and logs. Some websites don’t accept the command’s HEAD request. If you get a method-not-allowed response, remove --head and retry with a regular request. One successful request only proves that this request worked; it doesn’t mean every terminal process inherits the desktop proxy or that every domain uses the same route.

Keep a local recovery option before enabling TUN

Confirm that your system supports TUN and allows the client to perform the required network operations before enabling “Tun” in v2rayN. Turn off the desktop proxy first; change only the traffic-handling method. For the first test, use a session you can access directly—not your only remote management connection. If the logs report an unavailable device, insufficient permissions, or a route-add failure, determine whether the limitation comes from the system, a container, or permissions. Don’t make the network device accessible to every user as a workaround. If internal resources stop working after TUN starts, disable it to restore the original state, then check for a subnet conflict or overly broad routing rules.

Some users set proxy environment variables specifically for terminal apps. Those variables aren’t automatically cleared when the client exits, even if the desktop proxy setting is reset. If a new terminal works but an old one doesn’t, check whether the old session’s http_proxy, https_proxy, or all_proxy still points to the previous port. Also check uppercase variables and the tool’s own configuration files. Undo only the settings you added for this test so you don’t remove a proxy required by your work network. Then test one desktop app and one terminal request to confirm both are back to the expected state.

Android: Install v2rayNG or v2flyNG and route traffic through VPN

Choose a client, then select arm64 or a universal package

Start with v2rayNG in the Android download options. Choose v2flyNG only if your configuration provider specifically requires the V2Fly core. Many newer devices support arm64, but whether an app can install it depends on the architecture exposed by Android, not just the processor hardware. If you’re unsure, choose the universal package for the client you want. Universal packages usually include components for multiple architectures; they don’t resolve an incompatible Android version, insufficient storage, or device management restrictions.

After downloading the APK, open it from the system downloads list or a file manager. If Android requires permission to install apps from this source, grant it temporarily to the app that’s opening the installer—but only if you trust the source and device policy allows it. Revoke the permission after installation. If an update fails, check that the existing app is the same client and came from the same source before considering a signing mismatch. Don’t uninstall the old app as your first troubleshooting step; that may delete subscriptions and local settings. Export a backup using the available method first.

Updating a subscription doesn’t mean you’re connected

Open the client’s sidebar or main menu and go to “Subscription Group Settings” (sometimes shortened to “Subscription Settings”). Add an entry with a recognizable label and subscription URL, make sure the group is enabled, and save it. Return to the main screen and tap “Update subscription” in the upper-right menu. If the app lets you update the current group or all groups, update the new group first. For a single share link, use the clipboard import option under the main screen’s plus button instead of entering it as a remote subscription URL. When the list loads, tap a configuration, then tap the connect button on the main screen.

When you connect for the first time, Android asks whether to allow a VPN connection. Check that the app name in the prompt matches the client you just opened, then grant permission and check the client status and system VPN indicator. Without permission, the configuration list may still appear; that doesn’t mean traffic is going through the client. The VPN indicator confirms that the interface was created, not that the selected node is reachable. Next, test a webpage in the browser, then open the app you actually want to use. If the results differ, check whether that app is excluded by the per-app rules.

Per-app settings, background limits, and network changes

On Android, you usually don’t need to configure a manual proxy for Wi-Fi. The client uses the system VPN interface to receive traffic according to its routing and app scope, much like a virtual interface. If “Per-app proxy” or a similarly named option is enabled, check whether the list is an allowlist or a blocklist. Checking the same app can mean opposite things in the two modes. For a first test, turn off per-app rules to verify the basic connection, then change the scope for one app at a time. If the client asks you to reconnect after a change, follow the prompt before testing again.

Other apps using the system VPN interface may conflict with the current connection, including some local filtering tools. If the connection drops immediately after you tap Connect, open Settings → Network & internet → VPN, or a similarly named section, and check which app is using the VPN and whether Always-on VPN or Block connections without VPN is enabled. Some devices put these options under “More connection settings”; you can search Settings. Don’t replace a work-managed VPN yourself. Test for a conflict only in an environment where you’re authorized to do so.

If the connection drops when the screen is off but works again when it’s on, first check the client’s notification and logs. If the service stopped, check the app’s background restrictions in the system battery settings. If the service is still running but requests time out, test Wi-Fi and mobile data separately. Switching networks can invalidate existing connections even while the system VPN indicator remains visible. Once the underlying network is back, disconnect and reconnect, then confirm with a newly opened page. If only automatic updates fail, check the subscription update toggle and interval, as well as the background scheduling conditions. Update frequency doesn’t determine whether the current node can connect.

When you finish testing, disconnect with the client’s button and check whether another app still controls the system VPN. If Block connections without VPN is enabled, losing network access after closing the client may be expected. Understand why the restriction is enabled before changing it, and let someone authorized decide whether to adjust it. Don’t treat disabling the restriction as a general fix.

Verify the connection: test each layer and restore settings

Start with the local endpoint, then check the active configuration

A useful connection check answers three questions: did the app send the request to the client, did the client use the expected configuration, and did the destination respond? On desktop, confirm the active configuration in the main window, then check the logs to see whether the local endpoint started. If a connection to the local port fails, the request probably hasn’t reached the remote server. If the local endpoint receives the request but the remote handshake fails, check the active node’s settings, device time, current network, and information from the configuration provider. On Android, you don’t need to enable LAN listening for this test; compare the app’s access time with the client logs.

For a controlled comparison, open the same webpage in the same app, then try a second page to distinguish a site-specific problem. When testing another app, keep the node and routing unchanged. Start a new connection—for example, open a new window and reload—instead of relying on a page that’s already loaded and may be displayed from cache. If the client logs show requests, compare the timestamp, destination domain, and matched outbound. Log filters may hide connection details, so “no logs visible” alone doesn’t prove the client isn’t handling traffic. Use the logs, client status, and actual access results together.

Check DNS, routing, and proxy scope separately

DNS resolution finds the address associated with a name; routing determines which outbound path a request takes. Successful resolution doesn’t mean the right route matched, and a domain in a routing rule doesn’t guarantee that the app passed the domain name to the core. An app may resolve the name itself and pass only an IP address; a browser may also use its own encrypted DNS. If a domain fails in just one app, check that app’s DNS settings first. If name lookups fail across the whole device, compare DNS settings in the system, client, and current network to find where the failure starts.

The minimal JSON snippet below illustrates a core routing policy field. IPIfNonMatch means that for a destination specified by domain name, the core first tries to match existing rules and, if none match, tries resolving the name to an IP address so it can check IP rules. It doesn’t define direct and proxy outbounds for you, and it doesn’t change the app’s DNS behavior. If your custom configuration already has a routing object, check core compatibility before merging the field and keep your existing rules. Don’t replace the entire file with this snippet. In the v2rayN GUI, find the policy under “Settings → Routing Settings.”

{
  "routing": {
    "domainStrategy": "IPIfNonMatch"
  }
}

Even with the correct policy field, outdated domain or address lists referenced by your rules may prevent the expected result. First check which rule matched, then see the guide to updating routing rule files. If you suspect DNS queries are taking an unexpected route, see DNS testing and configuration. Don’t rely on a single line from one test site as a complete check, and don’t replace rule lists, DNS servers, and routing modes all at once without a record of how to revert them.

Undo changes in reverse order

When you’re done testing, turn off the last traffic-handling method you enabled, remove any temporary proxy settings in apps, then quit the client. If you used TUN, wait for its virtual interface and routes to be removed before switching networks. If you used the system proxy, check system settings for a leftover loopback address or restore the previous work configuration. If the network is still down after you turn the client off, restore basic connectivity instead of repeatedly clearing the subscription. Confirm the device is connected, check whether you need to sign in to a captive portal, verify proxy and VPN status, then retest with a destination that normally connects directly.

Verify the rollback too: with the proxy off, the device should behave as it did before testing. That doesn’t mean every destination must be reachable in the same way. If you had custom DNS, a work proxy auto-configuration script, or per-app rules, undo only the changes made for this test. Write down a brief result for each test, such as “System proxy only; browser worked; app unchanged,” before moving on. If something breaks, the last known-good result is more useful for finding the cause than reinstalling the entire client.

Common setup questions: troubleshoot by symptom

Subscription saved, but why is the list empty?

First check the logs to see whether an update request was sent. If not, confirm that you actually saved the subscription, enabled the group, and chose to update the current group or all groups. If a request was sent but timed out, first confirm that the device has basic network access. Then distinguish an unreachable subscription URL from an unreachable remote server in the configuration; these usually aren’t the same server. If the response is empty, the link may have expired, returned a sign-in page, used the wrong format, or contained configurations the client filtered out. Don’t assume an empty list means every node is down. Check the subscription source and its documentation.

If you know the update endpoint must be accessed through a working proxy, keep that working configuration, verify the connection, then choose an option such as “Update all subscriptions (through proxy).” Without a working configuration, don’t get stuck in a loop where you need an update to connect and a connection to update. For help with timeouts, certificates, and empty lists, see subscription update troubleshooting. If you see a certificate error, check the system time and the server’s certificate details. Don’t make ignoring certificate errors a routine setting.

Browser works, but why do other apps behave the same?

The most common reason is that the browser reads the system proxy while another app uses its own network stack or a separate proxy setting. Check the app’s network or connection settings for options such as “Use system proxy” or “Manual proxy.” If it has a manual proxy setting, test with the protocol and port the client is actually listening on. If you need TUN, note the original system proxy settings, clear the changes made for this test, then enable TUN on its own. On Android, check the system VPN status and per-app list first. Don’t enable desktop LAN listening for other devices just to troubleshoot an app on this one device.

An app that loads its home screen but fails to log in or sync may not have a traffic coverage problem. Login and sync often use different domains and may reuse existing connections. Quit and reopen the app, perform a repeatable action, then check connections and routing matches in the logs for that time. If only one service fails while other requests through the same configuration work, keep the working configuration and investigate that service’s connection requirements, DNS results, and access restrictions.

After enabling TUN, why can’t I access the intranet or some websites?

Turn off Tun first and check whether the same destination works in the previous mode. If the problem consistently follows the toggle, check whether the client’s routing policy covers local addresses or internal domains, then check whether internal name resolution depends on DNS from the current network. If you can reach the local gateway by IP but not by its internal name, focus on DNS rather than deleting all routing rules. If both the address and name fail, check for another tool changing routes and confirm that disabling TUN actually restores access. On managed corporate devices, ask your administrator about network ranges and client compatibility.

No internet after quitting the client—do I need to reinstall?

Not yet. First check whether the system or app still has a proxy pointing to a local port. Once the client exits, nothing may be listening there. On desktop, reopen the client, select “Clear system proxy,” then quit normally. If the device used a work proxy, restore its previous settings. If only one app is affected, check its manual proxy settings and extensions. If you stopped the Android client, check the system VPN settings for a Block connections without VPN option. The device administrator or owner should decide how to handle it based on the existing requirements.

What should I include when asking for help?

Include the operating system and processor architecture, client name, traffic-handling mode, and the step where the problem starts. Share only the log lines needed to show what happened, with subscription URLs, account details, connection credentials, and private internal addresses removed. Say whether the device can connect with the client off, whether the issue affects just one network or app, and how you can restore access. This helps readers distinguish installation, subscription, proxy endpoint, routing, and remote-server problems. Check the glossary if you need a definition, or return to the Getting Started guide to follow the standard setup again. Don’t tear down a configuration you’ve already verified works.