V2Ray Setup Guide
Quick Start walks you through your first connection. This page is a platform-by-platform reference: start with the general setup, then jump to your device. If the client is already installed, go straight to connection checks and troubleshooting.
Before you start: installers, subscriptions, and traffic routing
Check your system and choose a client
For desktop, start with v2rayN; for Android, start with v2rayNG. Consider v2flyNG only when your configuration provider specifically requires the V2Fly core and you have confirmed that the protocol, transport, and security layer are supported. The client is the interface for saving configurations, connecting, and managing runtime status; the core handles proxy protocols and routing. Two clients may import the same share format without supporting every option it contains. In particular, an Android client is not simply a desktop client ported under the same name: their traffic-capture methods and app coverage differ.
Open the client downloads page and choose a package for your operating system and processor architecture. Check the architecture in system information or among the device's supported app architectures; don't guess based on when the device was released. Keep your existing client and back up its configuration before trying a new package. If the old client is still running in the background, quit it from the tray or status menu before testing—not just by closing its window. Two instances can compete for the same local port or overwrite system proxy settings.
| System | Client | How to choose |
|---|---|---|
| Windows | v2rayN | This site offers x64 desktop and classic WPF editions |
| macOS | v2rayN | Choose arm64 for Apple Silicon or x64 for Intel |
| Linux | v2rayN | Choose deb or rpm, then check whether you need x64 or arm64 |
| Android | v2rayNG、v2flyNG | Choose the matching package if arm64 is supported; if unsure, check the universal package |
Subscriptions, individual shares, and backups are different
A subscription URL points to a list that can be fetched again. It's usually saved as a subscription group, which you then update; saving the URL only registers the source—it doesn't download the list. A single share link or QR code typically imports one configuration and won't update automatically with the original subscription. Client backups may also include groups, routing, and local settings. They're mainly for restoring the same client, not for exchanging configurations across platforms. When moving between devices, copy the subscription or individual configurations you need, then check traffic routing on each device. Don't overwrite another platform's setup with a full backup exported elsewhere. For more guidance, see How to sync V2Ray configurations across devices.
Subscription URLs may contain access credentials. Never paste one into a public support ticket, online decoder, or chat screenshot. For troubleshooting, note the time of the failure, the error type, and the response status. Before sharing logs, remove URL query parameters, account identifiers, and server details. If an update returns a login or information page, the source probably isn't serving a client-readable configuration; changing the import method won't fix that.
Start by testing one connection
After importing, select one known-working configuration and keep the default routing. First check that the local proxy handles requests, then expand traffic capture. On desktop, the system proxy gives apps that read system settings a proxy endpoint; TUN uses a virtual interface and routes traffic within a selected scope. Android clients often use the system VPN interface to capture app traffic, so granting permission is part of starting the connection. Identify which method is active before testing apps. Enabling multiple traffic-capture methods at once may work, but makes it hard to tell which one handled the request.
Windows: Install v2rayN and configure the system proxy
Download, install, and launch
Go to the Windows downloads page and choose the desktop or classic WPF edition. The desktop edition uses a cross-platform UI framework; WPF is Windows-only. Their layouts and settings may differ, so just test one. Open Settings → System → About to check your system type and processor; don't assume the x64 package is native to every Windows device. If you already use the WPF edition and only want to update your configuration, there's no need to switch editions just to import a subscription.
Follow the installer prompts. If you downloaded an archive containing program files, extract the entire archive to a fixed directory you can read and write to, then launch the app. Don't run it from the archive preview or copy only the executable. If the app explicitly reports a missing runtime on first launch, check the required runtime type and architecture. A window opening confirms that the UI is running, not that the core has started. If the log reports a missing file after you select a configuration, first check that the package's files and directory structure are intact, then verify which core is in use.
Update the subscription and select a configuration
In the main window, open Subscription Group → Subscription Group Settings, add a group, and fill in Remarks and Optional URL. Make sure updates are enabled for the group. For your first test, leave Filter blank so keywords don't hide a successfully downloaded list. Save, return to Subscription Group, and choose the option to update the current subscription without using a proxy. If the source really does require an existing connection, test that connection separately; don't make a new subscription depend on a configuration that isn't working yet. For filtering multiple providers, see Subscription groups and server filters.
After the update, make sure the list is showing the new group, not an old group or the current search results. Select a server and set it as active. Check the client log for configuration parsing errors, port conflicts, or startup failures. After switching the active server, reload the test page or start a new connection; existing long-lived connections may not switch over. Seeing a server in the list only confirms that it was imported—it doesn't complete this step.
Test the system proxy first; use TUN only if needed
To test with a browser that reads the system proxy, choose System Proxy → Automatically Configure System Proxy in v2rayN. “Do not change system proxy” means the client won't modify system settings; it doesn't turn off a proxy that was already configured. To remove settings written by v2rayN, choose Clear System Proxy, then check Settings → Network & Internet → Proxy in Windows. If the device previously used a manual proxy or script, you may need to restore it from your notes after clearing—don't assume Windows will restore it automatically.
If the browser works but a desktop app still connects directly, check whether that app has its own proxy settings. Try v2rayN's Enable TUN option only if you need to capture traffic from apps that don't read system settings. Before switching, remove the system proxy set during this test to avoid overlapping traffic capture. TUN creates a virtual interface and changes routes; grant permissions as prompted by the client or operating system. Don't run every app as administrator just for testing. If LAN access changes after enabling TUN, turn it off to restore the previous route, then decide whether specific routing changes are needed.
Check for lingering tray processes, port conflicts, and lost connectivity after quitting
If a port still appears busy after closing the window, check the tray for an older instance and make sure another copy of the client isn't running. Identify which process owns the port before deciding whether to quit it or assign a different port in the client. After changing ports, update any manually configured browser, developer tool, or terminal settings. Reapply the system proxy once the new port is listening. If the browser stops working after you quit the client but recovers when you turn off the system proxy, the system is probably still pointing to a local port that is no longer listening. If only one app fails, check whether it has its own saved proxy address.
macOS: Choose the right build, network service, and permissions
Mount the disk image and launch the app
Open the Apple menu and choose About This Mac. On an Apple silicon device, choose arm64 from the macOS downloads page; on an Intel Mac, choose x64. Having a compatibility layer installed doesn't mean you should prefer a package for a different architecture. The desktop app and its bundled core runtime may also have separate architecture requirements. Before replacing a package, quit the running app. Don't launch two copies of v2rayN from old and new folders at the same time.
Open the disk image, follow its instructions to copy the app to Applications, then launch it from that folder and eject the image. This gives you a consistent launch location and makes it easier to tell which copy is running. If macOS shows a security alert, check the app's source and processor architecture, and distinguish a normal first-launch confirmation from an organization policy or an app that can't run. Don't disable system-wide security for a single app. If the window is blank or the app quits immediately, first check whether the app itself is running before investigating connection settings; otherwise, a launch problem may be mistaken for a subscription issue.
Add and update a subscription in v2rayN
Open Subscription Group Settings in the main window, add a group, and enter the complete URL provided by the source in Optional URL. Save, update the subscription, then select the corresponding group to check the result. If you received a single share link, use the clipboard import option instead of pasting it into the subscription URL field. If the address is rejected, check whether you copied explanatory text, a line break, or quotation marks along with it. Don't remove query parameters just because they look unfamiliar.
Once the list appears, select an active server and check the log for obvious core startup errors. If you're moving from Windows, you can reuse the subscription URL, but don't blindly copy system proxy settings or paths to local files. Even with the same subscription, two devices may need different active servers, routing groups, or LAN access. Get one configuration working first, then restore extra settings one at a time to identify whether differences come from the imported configuration or local parameters.
Check proxy settings for the active network service
First choose Automatically Configure System Proxy in v2rayN. Then open System Settings → Network, select the active network service, and check enabled options and the local address under Details → Proxies. Proxy settings apply to a specific network service. If you switch between Wi-Fi and Ethernet, check which service is actually carrying traffic. Browser access doesn't mean terminal commands use the system proxy; some command-line programs only read their own options or environment variables. If the browser and terminal tests differ, don't immediately assume the browser result is invalid.
If the device previously used an automatic proxy configuration file, note whether it was enabled. After testing, undo your changes and restore the original state; don't leave two automatic configurations active together. If the client asks for permission to change system proxy settings, make sure the prompt corresponds to the action you just took. On a managed device where changes aren't allowed, leave the settings alone and test with an app that supports a local proxy. A successful local proxy test proves that the client path works, not that you have permission to change system-wide settings.
Test TUN and network switching separately
Only check TUN if you need to capture traffic from apps that don't use the system proxy. Confirm that your v2rayN build and selected core support TUN, then grant any required permissions. An enabled switch doesn't prove that the virtual interface is capturing traffic; check the client log and test with a new connection. If internal domains or LAN services stop working, turn off TUN and test the previous route on the same network. If the problem appears after waking from sleep or switching networks, check the active network service and client status first. You usually don't need to reimport the same subscription to fix a problem that started after switching.
Linux: Choose a package, configure desktop proxy, and check routing
Choose a package by distribution and architecture
Open the Linux downloads page. Debian, Ubuntu, and similar distributions use deb packages; Fedora and others use rpm. Matching the package format is only the first step: your distribution still needs the declared dependencies and a supported graphical session. Don't treat the desktop client as a service for a headless system, or try to install a package in a different package-management system just because it can be unpacked.
Run the two read-only commands below to check your system architecture and distribution ID. The common output x86_64 corresponds to x64 on the download page; aarch64 corresponds to arm64. If you're running the commands in a container or remote terminal, make sure you're checking the system where you intend to install the desktop client—not a different environment.
uname -m
grep -E '^(ID|ID_LIKE|VERSION_ID)=' /etc/os-release
After downloading, open the package with your distribution's software installer. Alternatively, enter sudo apt install or sudo dnf install in a terminal, followed by the absolute path to the downloaded file. If the path contains spaces, enclose the entire path in quotes. Let the package manager resolve dependencies; if there's a conflict, check the package name rather than forcing the install. Once installation is complete, launch v2rayN from the app launcher as a regular user. Running the entire graphical app as an administrator changes ownership of its configuration, and your regular account may then be unable to access saved groups or settings.
Update the subscription and establish a local listener baseline
Add a note and subscription URL in Subscription Group Settings, save, and update the relevant group. If the update reports results but you can't see any entries, clear the search in the main window and check the group's filters. Select an active server and confirm that the core starts successfully. If the log reports a startup failure, first fix local issues such as missing dependencies, a package for the wrong architecture, or a port conflict. Repeatedly updating the subscription won't create a local listener.
Use ss -ltn to view current TCP listening addresses and ports, then compare them with the local listener settings in v2rayN. A listener only shows that a program has bound to the port; it doesn't prove the program is v2rayN or that a remote connection has been established. If the same listener appears when the client isn't running, check for another proxy app. Don't terminate an unfamiliar process. You also don't need to expose the local listener on every network interface just to connect apps on the same machine.
Test desktop proxy, terminal settings, and TUN separately
Try Automatically Configure System Proxy in v2rayN, then check the network proxy settings in your desktop environment. GNOME, KDE, and other environments have different settings and support; some apps only use their own proxy configuration. A proxy environment variable set in one terminal doesn't mean desktop apps inherit it. Conversely, changing the graphical settings doesn't guarantee that already-running command-line programs will reload them. To isolate the difference, test the same destination once with an explicit proxy and once in a desktop app; don't generalize from one result to every program.
Before using TUN, check the client log to confirm that the selected core supports it, and make sure the system provides a virtual network device and permits the required route changes. The read-only checks below can help distinguish a missing device from one the app isn't authorized to use. Normal output doesn't prove that permissions are sufficient. In containers and managed machines, permissions may also be restricted by the host environment. Ask an administrator to grant access for the intended use; don't loosen device permissions system-wide as a general fix.
ls -l /dev/net/tun
ip route show default
Don't lose remote access by changing routes
Before enabling TUN over a remote desktop or terminal session, make sure you have local console access or another way to recover. An unchanged default route doesn't prove that traffic wasn't redirected; policy routing may also be in effect. If you only need to verify the installation, an explicit local proxy test is enough—you don't need to change global network settings first. After switching back from TUN, check that the desktop proxy still points to a working port before continuing. If trouble starts only after switching Wi-Fi networks or waking from sleep, check traffic capture status before reinstalling the package.
Android: Install the app, import a subscription, and route traffic through VPN
Choose a client and app architecture
Get v2rayNG first from the Android downloads page. Choose v2flyNG only if you specifically need the V2Fly core and your configuration is compatible. Both offer arm64 and universal packages. A “64-bit” processor doesn't guarantee that the system supports arm64 apps; check the app architectures supported by the device's operating system. If arm64 is supported, choose that package. If you're unsure, try the universal package—but it won't work around an unsupported OS version.
When you open the downloaded file, Android may ask you to allow the browser or file manager you're using to install apps. This permission is for the installation source, not for connecting. Allow it temporarily only when needed, and revoke it after installation if you wish. If Android reports a conflict with an existing app, don't uninstall it right away. Check whether you're trying to replace an app signed differently or whether another copy is installed in a work profile. Uninstalling may erase local groups and routing settings; back them up somewhere trusted before deciding whether to migrate.
Add a subscription or import a single configuration
In v2rayNG, open Subscription Group Settings from the side menu, add a group, enter a note and URL, and save. Return to the server list and choose Update subscription from the top-right menu. In v2flyNG, also distinguish the subscription settings in the sidebar from the update action in the list; menu labels may differ between interfaces. For a share link, use the clipboard import option in the main screen's add menu. For a QR code, use the scanner and grant camera access only when you need to scan it.
After updating, switch to the relevant group, check that entries appear, and select an active server. It's easy to copy explanatory text along with a URL on a phone. If an update fails, copy the full URL again from the source and remove any surrounding whitespace; don't edit its parameters by hand. If you're using a single share link, save it again or make a supported backup before changing devices. An update can't restore an item that was never part of a subscription.
Connect and check which apps are covered
Tap Connect on the main screen. The first time you use VPN mode, accept Android's connection request, then check the client status and the system VPN indicator. This uses Android's VPN interface to route device traffic; you don't need to look for the desktop “Automatically Configure System Proxy” menu. If another VPN is already enabled, check whether it's for a work profile, a managed connection, or an always-on VPN. Don't replace it until you know what it's for. The system icon only confirms that the interface is up; make a new request to verify the connection.
If per-app proxy is enabled in v2rayNG, check whether the app you're testing is included in the selected scope, and whether the list is set to include or exclude apps. Selecting an app doesn't always mean its traffic will be captured; it depends on the current list mode. If you test with a browser that's excluded, the result won't represent all apps. After changing the scope, reconnect as prompted and send a new request from the target app; don't rely on a session that was already open.
Tell apart screen-lock disconnects, network changes, and system restrictions
If the app works in the foreground but disconnects when the screen locks, check the app's battery settings, background restrictions, and VPN status. Change settings only for the app that's affected; there's no need to disable power-saving features across the device. If Wi-Fi works but mobile data doesn't, check mobile data permission and the client log, then compare using the same active server. If the whole device stays offline after disconnecting the VPN, check Android's always-on VPN setting and the option to block connections without a VPN. Ask the administrator to review settings on managed devices. Don't mistake system restrictions for an expired subscription.
Test the connection: find where requests fail
Keep a direct-connection test for comparison
Before connecting, choose a stable HTTPS page you can access and check whether it opens a new connection on your current network. If the network requires sign-in, complete that step on its login page before enabling the client. Keep the network, destination, and app the same during testing; don't change the server, protocol, and proxy mode at once. If direct access also fails, fix the underlying network first. Otherwise, you can't tell whether the client caused the difference or the test destination was already unreachable.
Next, select an active server, watch the log, and check the local listener or Android VPN status. Separate the results into three questions: did the client load the configuration, did the core start, and did the request use the intended entry point? An entry in the list answers only the first. A green switch or system icon mainly indicates the second. Confirm the third with a new connection and the relevant logs. Browsers may reuse connections or serve cached content, so don't rely only on whether an already-open tab still loads.
Run a repeatable desktop test with an explicit proxy
The command below is for desktop devices with curl installed, where the client provides a SOCKS service on the loopback address at port 10808. Check the protocol, address, and port in v2rayN settings or logs first; if they differ, replace the command values with your actual settings. On Windows, use curl.exe explicitly to avoid shells that interpret the short name as another tool. The example requests a public test site, includes no account information, and doesn't require enabling the system proxy.
curl --max-time 15 --socks5-hostname 127.0.0.1:10808 --head https://example.com/
--socks5-hostname sends the target hostname to the SOCKS service for resolution, unlike having curl resolve it locally before making the request. This can test the explicit proxy path, but it doesn't reveal the browser's DNS path or prove that every app is being routed through the proxy. If the local port can't be reached, check the listener address and protocol first. If the request reaches the local listener but then times out, check the logs around that request for outbound routing, DNS resolution, and the remote handshake. An HTTP response means the request reached a service that responded; some status codes still indicate that the destination refused access, so don't treat every response as success.
Check traffic capture, routing, and DNS separately
If an explicit proxy test works but the browser doesn't, first check whether the browser reads system proxy settings or has its own overriding configuration. If only TUN fails, check its startup logs and the affected apps, then compare LAN access and behavior after switching networks. If domain-based routing isn't behaving as expected, confirm that the client captured the request before reviewing the domain rules and their order. Changing dozens of routing rules won't affect a request that never reached the client.
The same domain can resolve to multiple addresses, and domain rules and IP rules operate at different layers. If an app resolves a domain itself and passes an IP to the client, the request may not match the domain rule you expect. Entering an IP directly can also fail because of HTTPS certificates or virtual-host configuration, so that doesn't rule out a DNS problem. When the logs show a matched rule or outbound, use that evidence first. To check the rule database, see How to update GeoIP and GeoSite rule databases. Don't change the rule database and routing order in the same test.
Common configuration issues: what to check next
Subscription update fails, or succeeds but shows no entries
When an update fails, first confirm which group you're testing and whether the request is set to use an existing proxy. A common first-import mistake is trying to fetch a new configuration through a proxy that isn't working yet. Break the update into three questions: could the request be sent, did the source return content, and could the client read it? For a timeout, check the network path. For an explicit access denial, ask the source about authorization and the correct endpoint. If the returned content can't be read, check whether it's a compatible subscription, a login page, or another kind of configuration file. Don't paste the subscription itself into an unnecessary third-party service.
If the update reports success but no entries appear, switch to the right group, clear the search, and temporarily disable keyword filters before updating again. If other groups still contain entries, there's no need to clear all configurations. Before deleting and recreating a group, check for locally edited entries and whether an update will replace them. If only one share link is incompatible, test that item by itself rather than combining every source in one group. For more interface questions, see FAQ.
The list is populated, but the active configuration fails to start
First make sure an active server is selected, then read the earliest meaningful error in the log. The address, protocol, transport, and security layer must be compatible. For example, an imported entry may show the server address while missing or misreading transport parameters, so it looks fine in the list but fails at startup or during the handshake. If the error mentions an unsupported field or protocol, check which core is running and ask the configuration provider for a compatible setup. Don't disable TLS verification as a general handshake fix. First check system time, the connection address, and the server name for consistency.
If the error is about a port conflict, missing file path, insufficient permissions, or the wrong architecture, fix the local environment first. These issues happen before the client reaches the server, so switching servers won't help. If the local core starts but one configuration repeatedly fails during the handshake, compare it with another known-working configuration on the same network. If both fail, recheck the shared connection path and routing rather than blaming a single configuration for every symptom.
Browser works, other apps don't—or connectivity drops after quitting
Apps may use different proxy paths. On desktop, check the app's own proxy settings, system proxy, and terminal environment variables. On Android, check per-app scope and system VPN status. Some apps don't work in a proxy environment; others need specific internal network resources, so capturing more traffic isn't always the right fix. If only the desktop browser loses access after you quit the client, check whether the system or browser still points to the local proxy. If every Android app is affected after disconnecting, check whether system settings block connections without a VPN.
To restore the original setup, undo changes in reverse order: turn off TUN or disconnect the VPN, check the system proxy and app-specific settings changed during this test, then retest the underlying network. Don't clear organization-managed proxy or VPN policies, and don't reinstall as a first step. Reinstallation can replace program files but may leave system proxy settings, existing configuration folders, or device-management policies unchanged. Reinstall only when you've identified damaged installation files, an architecture mismatch, or an update conflict.
Record what you found, not just “it won't connect”
Record the operating system and architecture, client name, traffic-capture mode, whether an active configuration was selected, and whether the failure occurred during update, startup, or a new connection. Include a comparison—for example, an explicit proxy works on the same network but the system proxy doesn't, or the problem starts only after switching networks. Keep only the log excerpts needed to reproduce the issue, and remove subscription URLs and account details. To start over, return to Quick Start and follow the main sequence: import, select, route, and test. Once it works, restore extra settings from the section for your platform.