v2rayN Setup Guide

Before You Start: Client and Subscription URL

This guide is for users who have installed a client and are ready to set it up for the first time. The process usually takes about 10 minutes, though the subscription URL's validity and network access can affect how long it takes. If you haven't installed a client yet, visit the Get a client page, choose a package for your operating system and CPU architecture, install it, and open the main screen before returning here. For the initial setup, keep the default listening port and avoid changing DNS, TUN, or custom routing at the same time. This makes issues easier to isolate.

Get your subscription URL from a trusted service provider. The client cannot generate a working service configuration on its own. A subscription URL usually points to a list of configurations; it is not a sign-in or management page, nor a regular webpage share link. Copy the full URL, without leading or trailing spaces, line breaks, or punctuation added by a chat app. It may contain personal access credentials, so don't post it publicly or share screenshots that show the full URL.

Before you begin, make sure your device's clock is reasonably accurate and note whether any other proxy tools are running. For the initial test, use just one client to handle traffic so multiple programs don't keep changing the system proxy. If you only have a single share link rather than a subscription URL, you can import it from the clipboard, but that adds just one configuration and won't enable automatic subscription updates. This guide follows the subscription workflow.

Step 1: Import a Subscription

Create a subscription group, then update the configuration list. Saving a URL to a group does not fetch server entries by itself. You'll know this step is complete when selectable configurations appear on the main screen—not merely when a URL is saved in the settings window. Give the group a recognizable name, such as “Daily subscription,” so you can identify it when updating later.

v2rayN: Save the Group, Then Update

On the main screen, find “Subscription Group” and open “Subscription Group Settings.” Click Add or New. Enter a group name in the remarks field, paste the full URL into the subscription URL field, leave the other options at their defaults, and save. If subscription management is in a separate sidebar in your version, open the group's edit window and enter the same two fields: remarks and URL.

Return to the main screen, open the “Subscription Group” menu, and choose the subscription update command. If you haven't established a working connection yet, start with “Update without proxy.” If your current network can't reach the subscription URL, check the access requirements rather than repeatedly changing unrelated settings. If you already have a working connection and the provider requires proxy access, choose the corresponding update option. When the update finishes, select the group and check for configuration details such as server names, addresses, or protocols.

v2rayNG: Add the URL, Then Update from Home

Open “Subscription Group Settings” from the home screen menu, tap Add to create a group, enter the remarks and subscription URL, then save. Return to the home screen and choose the subscription update command from the menu. Some versions let you update only the current group; make sure the target group is selected first. When the update finishes, new configurations should appear on the home screen. Tap one to select it for the connection.

If the list is still empty, check whether the update failed while fetching the URL or parsing its contents. A fetch failure usually points to the URL, network, or access permissions. A parse failure may mean the response isn't a subscription the client recognizes, but a sign-in page or an error page instead. Don't submit your subscription URL to an unknown conversion site. For more on link types and subscription formats, see the client and subscription entries in the Glossary.

Once configurations appear, choose one that explicitly supports your client and continue. Don't import multiple subscriptions from the same source at once. Subscription updates usually replace entries generated from that subscription, so avoid repeatedly editing their service settings directly. If you need to keep changes, make a separate copy. You don't need to enter protocol fields manually for this initial setup; the next step is to configure proxy access and routing.

Step 2: Choose a Proxy Mode

Separate two settings: how apps send requests to the client, and how the client chooses an outbound route for those requests. The system proxy mainly handles the first; routing modes handle the second. “Global” generally means traffic that has already reached the client prefers the proxy outbound—it doesn't automatically route every app on the device through the client. Keeping these layers separate gives you a clear target for testing.

v2rayN: Configure the System Proxy and Routing Separately

Find “System Proxy” on the main screen or in the tray menu. For apps that follow system proxy settings, such as browsers, choose “Automatically configure system proxy” or the equivalent option. “Clear system proxy” removes this method of routing traffic; “Do not change system proxy” generally leaves the current setting as is and doesn't confirm that the proxy is configured. Your operating system may show additional permission prompts; rely on the client's reported result.

Next, open the “Routing” menu. For everyday use, start with the built-in “Bypass mainland China” rule or an equivalent direct-routing rule available in your version. These rules generally send matching domains or address ranges direct, while handling other requests according to the default outbound. Don't infer every detail from the rule name; use a built-in option and leave its rule order unchanged for now. To rule out routing as a cause during testing, you can briefly switch to global routing and then restore your usual mode.

v2rayNG: Check Routing and Per-App Scope

Check the current routing mode in Settings or Routing Settings. Start with the built-in “Bypass mainland China” option or a similar mode. For the initial test, leave per-app proxying off so the test app remains in the default scope. If you already have a per-app list, make sure the browser isn't excluded. Android's system VPN interface receives traffic, while routing rules determine the outbound; this isn't the same as setting a system proxy on desktop.

Save your changes and return to the main screen. Confirm that the selected configuration hasn't changed. For now, don't add custom DNS, complex per-app lists, or extra rules, and there's no need to enable TUN for the initial connection. Some desktop apps don't follow the system proxy and may need a proxy configured separately or another access method; that doesn't mean the server configuration has failed. See the Proxy Modes section of the user guide for details. For now, use a browser for a basic connection test.

Step 3: Connect

Once the subscription and proxy mode are ready, start the connection. First confirm the selected group and configuration so you don't use an outdated entry by mistake. A highlighted row, an active-server marker, and a running core are different things: a highlight may only indicate the row you're about to act on. Check the active marker and startup logs to confirm which configuration is in use.

v2rayN: Set the Active Server and Check the Core

Find the intended configuration in the server list, then use the right-click menu to choose “Set as active server” or the equivalent command. Some versions also let you switch by double-clicking; follow the interface prompts. The client usually loads the configuration and starts or restarts the core, so there may not be a single “Connect” button. Check that the active marker moves to the intended row, then look in the logs for configuration load failures, port conflicts, or core startup errors.

Once the core is running, check that the system proxy is still set. If you see a local listening port conflict, close other proxy tools and check that you haven't opened multiple client instances instead of changing several ports in a row. If you do change the listening port, update any manually configured proxy port in the apps as well. For a first setup, it's easier to resolve the conflict and keep the default. A successful startup log only confirms that the local service is running; it doesn't prove the remote connection works.

v2rayNG: Approve the VPN Request, Then Connect

Tap the target configuration, then tap the Start button at the bottom of the home screen. On the first launch, Android displays a VPN connection request. Verify that it comes from the current client, then approve it. The VPN indicator means the app has established a local traffic path; it doesn't guarantee that the remote server is available. Return to the client to check its status. If the button now offers Stop and no error appears, move on to testing.

If the connection stops immediately, check the app logs to see whether the issue occurred during configuration parsing, system authorization, or core startup. Android devices generally can't let two regular VPN apps handle the connection at once, so an existing VPN may be replaced when you start this one. If it works in the foreground but disconnects after running in the background, check whether Android's battery management is restricting v2rayNG. There's no need to change every battery setting before confirming the connection works.

When an error occurs, keep one concise, relevant log entry; don't change the configuration, routing, and DNS all at once. Logs may include server addresses or destinations, so remove personal details before sharing them. For common startup issues, continue with the Troubleshooting section of the FAQ. Once the client is running, verify it with a real request rather than relying on the status icon.

Step 4: Verify the Connection

A useful test checks app access, route selection, and remote reachability. A webpage loading only proves that the request reached its destination; it doesn't by itself show that the proxy handled it. Likewise, one failed request doesn't mean every configuration is unusable. First open a page that normally works to confirm basic connectivity, then test a destination that should use the proxy under your current rules. Use the same browser for both checks where possible.

Make a New Request and Check the Outbound in the Logs

On desktop, open a new tab in a browser that follows the system proxy and visit the target page. If the browser has a separate proxy extension, pause it so it doesn't override the system settings. On Android, make sure the test app isn't excluded by per-app routing, then try the destination. An old page may be cached, and existing connections may keep using their previous route, so reload the page or restart the test app before drawing conclusions.

Find the request's destination in the client logs or connection records. If your version shows outbound details, check whether the request went direct or through the proxy and compare that with the routing rule you chose. A direct connection that loads successfully doesn't prove the proxy works. If the request used the proxy but failed, check server reachability and configuration parameters. Some versions show limited detail by default; you can temporarily increase the log level for one test, then restore it to avoid recording too much browsing activity.

Run a Controlled Retest with Global Routing

If you're unsure which rule should match the destination, briefly switch to global routing, keep the same active configuration, and send a new request to the same destination. If it works in global mode but not with your usual rules, check the rules and domain resolution first. If it fails in both modes, verify that the app is reaching the client, then check the configuration and network. Global routing still can't bring an app into the client if it's outside the access scope, so don't skip that check if switching modes makes no difference.

Once the connection is confirmed, restore your usual routing mode and reopen the apps you normally use. Check that both direct and proxied access behave as expected. If only one app has a problem while the browser test works, check whether it follows the system proxy, is excluded by an app list, or is reusing an old connection. To learn more about how domain rules, IP rules, and DNS work together, see the Routing section of the user guide. You don't need to explore every setting during the initial setup.

Stop the Connection and Restore Network Access

Before closing the desktop client, choose “Clear system proxy” so apps don't keep sending requests to a local proxy that has stopped. Whether the proxy is cleared automatically on exit depends on the version and settings. If your browser can't connect after you quit, check for a leftover manual proxy in your system network settings. On Android, tap Stop in v2rayNG and confirm that the system VPN indicator disappears, then test that your usual apps can access the network normally.

By now, you should be able to identify your subscription group, active configuration, access method, and routing mode, and stop the connection correctly. For later subscription updates, return to the relevant group, update it, and check that the active configuration is still available; there's no need to repeat the full setup. After confirming the first connection works, explore TUN, DNS, or custom rules only as needed. Change one setting at a time and repeat the request-and-log check to keep troubleshooting clear.