Getting started / First-time setup
v2rayN Setup Guide
Import a subscription and test your connection
Complete a basic setup in four steps: import a subscription → choose a proxy mode → connect → verify access. Allow about 10 minutes. Get browser access working before trying TUN or custom rules.
Before you start, get the right client for your device from the Download Center and open its main screen. You’ll also need a valid subscription URL you’re authorized to use, or an individual share link. The client reads configuration and connects to servers; installing it does not provide servers automatically. This site does not provide subscription URLs.
This page covers your first connection only. If errors persist, save the exact error message and go to Troubleshooting. You don’t need to change DNS, the core, and transport settings all at once during initial setup.
Step 01 / Get servers to appear in the list
Import a subscription
First, identify what you have. A subscription URL is usually a link that can update multiple configurations. An individual share link usually starts with a protocol name and contains one server configuration. Each has a different import method. Use the source page’s copy button where possible, and avoid selecting explanatory text, line breaks, or trailing punctuation. If you’re using a QR code, check whether it contains a subscription or a single configuration, then choose the matching scan option.
In the v2rayN main window, open “Subscription Group” and select “Subscription Group Settings,” then create a new entry. Add a recognizable label, such as “Daily,” and paste the full subscription URL into the address field. For a first-time setup, you usually don’t need to set a subscription converter or update proxy; leave the defaults as they are. Check that the URL hasn’t been cut off, then save and close the settings window. This only saves the URL; it’s normal for the server list to remain empty for now.
Subscription Group → Subscription Group Settings → New → Save
Return to the main window, select the group you just saved, and choose “Update current subscription.” Before you’ve established a connection, try the “Update without proxy” option first.
After the update, check the status area at the bottom or the log, then check the group filter on the main screen. If the update completes but the list is empty, select the group you just created and clear any search filters in case they’re hiding the entries. You should normally see server details such as a label, protocol, and address. Seeing an entry doesn’t mean it’s ready to connect; this step only confirms that the client recognized the subscription.
In v2rayNG, open “Subscription Group Settings” from the side menu, tap Add, enter a label and subscription URL, and save. Return to the main screen, open the more menu, and choose “Update subscription,” then check the relevant group. For an individual share link, copy the full link and use “Import from clipboard” in the main screen menu. Don’t paste a single link into the subscription URL field. The desktop client also has a server menu option to import from the clipboard.
If an update fails, first check whether the error says the URL request failed or the content couldn’t be parsed. For a failed request, check that the URL is still valid and accessible from your current network. For a parsing error, make sure you copied a configuration link rather than an information page or sign-in page. If you don’t already have a working connection, “Update through proxy” may not help because it depends on the connection you haven’t established yet. If you switch networks, make one comparison test; don’t keep creating the same group.
A subscription URL may contain private access credentials. Don’t post the full URL in public comments or screenshots. Keep a local copy and redact identifying details before sharing a problem. For the difference between subscriptions and individual configurations, see Glossary. For an empty list or failed update, see FAQ: Setup and installation. Once entries appear in the list, move on to proxy mode settings; there’s no need to test every server first.
Step 02 / Separate app traffic from routing
Choose a proxy mode
Once the server list is ready, decide how apps will send requests to the client. For an initial desktop browser test, “Automatic system proxy configuration” is the easiest place to start. Choose it from the system proxy menu in the v2rayN main window or tray menu, then leave the client running. This updates the system proxy settings so apps that follow them can use the client’s local listener. It doesn’t mean every connection from every app will be routed through the client.
“Clear system proxy” in the same menu removes the system proxy settings. “Do not change system proxy” leaves the current settings untouched; it doesn’t turn the proxy off. If you’ve used another proxy app, quit it first to prevent it from repeatedly overwriting the system settings. If your browser has its own proxy extension, pause it during testing so there’s only one clear route into the client.
Routing: start with Bypass mainland China
Next, check the routing option in v2rayN. For a first setup, use the built-in “Bypass mainland China” preset. The system proxy determines whether an app sends requests to the client; routing determines which outbound route handles those requests. The bypass preset typically sends connections matching mainland China domain or IP rules directly, while other connections follow the proxy rules. The exact behavior depends on the active rule set and match order. System proxy mode and routing mode are separate settings.
For a first setup, keep the built-in rules. You don’t need to edit geosite, geoip, or custom DNS at the same time. Switching to global proxy won’t fix an unavailable server; it only changes routing. Once the connection works, check the logs and investigate the rules if a site uses an unexpected route. If terms like direct and proxy are unclear, start with routing and split-tunneling terms. Save detailed rule-matching issues for Troubleshooting.
TUN mode: leave it off during the first test
TUN uses a virtual network interface to capture traffic from apps that don’t follow system proxy settings. It also adds extra requirements, including permissions, a virtual interface, and network routes. If you’re only testing a browser for the first time, leave TUN off in v2rayN. This keeps initial troubleshooting focused on the subscription, active server, and system proxy instead of whether the virtual interface was created successfully.
After the browser test succeeds, enable TUN if you need it and grant any permissions requested by the system. Test again after enabling it; a lit switch alone doesn’t prove it’s working. If another VPN or virtual networking tool is running, check whether it might conflict over network routes. If you’re not sure, disconnect the other tool temporarily and test TUN on its own. Follow the exact wording of any permission error rather than repeatedly toggling the switch.
v2rayNG connects through Android’s built-in VPN service, so there’s no need to look for the desktop “Automatic system proxy configuration” option. For the first test, keep the default app coverage and routing settings, and don’t exclude the browser you’re testing. An app-level bypass list can keep apps out of the client and make a working connection look broken. This sets the traffic entry method; next, choose the server that will handle the connection.
Step 03 / Set an active server and check startup
Choose a server and connect
Return to the v2rayN main window and choose a server in the group you just updated that you know is still valid. Use the right-click menu’s “Set as active server” or the equivalent activation option to make it the current server. Clicking a row may only select it; it doesn’t always make the server active. Check whether the active marker or status area changes. Don’t rely on the row’s highlight alone.
In v2rayN, activating a configuration typically starts or reloads the core; unlike the Android app, it may not show a prominent Connect button. After activating the server, check the main window’s log or status area for startup errors. Keep “Automatic system proxy configuration” enabled, as selected earlier. You can minimize the client window, but don’t exit the process.
A core startup message only means the local program has started; it doesn’t prove the remote server is reachable. Some connections aren’t made until the browser sends a request, so no traffic in the main window yet doesn’t necessarily indicate a problem. If the log shows a port conflict, insufficient permissions, or a configuration parsing error, stop here and fix the local startup issue first. Switching servers repeatedly won’t free a listening port that another program is using.
If your subscription contains multiple configurations, choose one the provider marks as valid and run one real connection test. A timeout only means that this test didn’t complete; the probe target, your current network, or the server itself could be responsible. Don’t judge a server by a single number. The goal of a first connection test is to load a real webpage, not to pick the server with the lowest displayed latency.
In the v2rayNG main screen, select the server you want to use, then tap Connect. The first time you connect, Android will ask to set up a VPN connection. Check which app is requesting permission, then approve it. Return to the client and check that the button or status shows a running connection. If another VPN is already connected, Android may ask to replace it. Confirm before testing; two apps can’t use the same Android VPN connection at once.
If the Connect button switches back to stopped immediately, open the v2rayNG logs and note the error closest to the startup time. If the connection only drops after the app goes into the background, check the system’s background activity and battery restrictions for the app. Test access while the app is in the foreground before changing background settings. This helps distinguish a connection that never worked from one Android stopped in the background.
Keep the current server selected and move on to the browser test. If you need to describe the issue to someone, note four things: whether the subscription was imported, whether the active server changed, whether the core started, and whether the system proxy or VPN is enabled. Don’t share the full configuration, especially addresses, user IDs, or password fields. Redact personal information from logs before sharing them too.
Step 04 / Test real access to confirm the connection
Verify that it works
Open a browser and make sure no separate proxy extension is overriding the system settings. In a new tab, load a known-working site that requires your proxy; don’t rely on a previously cached page. Then open a site that normally works without a proxy and check that it loads too. The first test checks the proxy route; the second checks that normal browsing hasn’t been disrupted.
With “Bypass mainland China” routing, a site that normally connects directly may still load even if the proxy isn’t working. Conversely, one site failing in the browser doesn’t prove the entire client is broken; the site itself may be temporarily unavailable. Compare two different known-working sites rather than repeatedly refreshing the same URL.
Check the client logs during the test. Matching timestamps and an entry for the destination or outbound route can help confirm that the request reached the client. The details vary by core and log level, so you don’t need to switch to the most verbose level just because individual requests aren’t shown. Look for clear errors and match them to the page you just opened; an old error may be unrelated to the current issue.
| What you see | Check first | What to try next |
|---|---|---|
| Browser can’t load the page; no matching request appears in the client | System proxy, browser extensions, and Android app bypass list | First, confirm the browser is sending requests to the client |
| Requests appear in the log, but connections keep timing out | Whether the active server is valid and reachable from your network | Try one different server known to be working |
| Browser works, but one app still can’t connect | Whether the app follows the system proxy or is excluded | Check how the app connects before considering TUN |
| An error appears at startup, before you open a webpage | Local ports, permissions, and configuration fields | Fix the startup error, then test access again |
To compare behavior with the proxy off, first choose “Clear system proxy” on desktop, then open the same site in a new browser tab. On Android, disconnect in v2rayNG instead. Restore the original setting after the comparison. Browsers may reuse existing connections or serve cached pages, so a page that still loads after disabling the proxy doesn’t necessarily mean the proxy wasn’t involved. If needed, close and reopen the browser before testing again.
If the browser works but one desktop app doesn’t, don’t import the subscription again. Check whether the app has its own proxy settings and whether it follows the system proxy, then decide if you need TUN. On Android, first check that the app isn’t on the bypass list. Investigate DNS or routing rules only after you’ve confirmed the basic connection path; otherwise, you may change settings at the wrong layer.
If both types of site load and the client has no ongoing startup or connection errors, keep the current setup as your baseline. Note the subscription group, active server, and routing preset; there’s no need to copy the full configuration elsewhere. When you change a setting later, test the same two sites. If anything breaks, revert that one change to narrow down the cause.
When you’re done, clear the system proxy on desktop before quitting the client. This prevents the system from pointing to a local port that’s no longer running. If you used TUN, turn it off too and confirm the network works normally. On Android, tap Disconnect in v2rayNG. If webpages still fail after you quit, check for leftover system proxy settings before deleting the subscription or reinstalling the client.