Getting Started About 10 minutes

v2rayN Setup Guide

Import a subscription, choose a proxy mode, then send a fresh request to confirm the connection is working.

Before you begin, make sure you have the client installed, a subscription URL you’re authorized to use, and an app you normally use to test connectivity. Need to install a client? Choose one from the download center.

Import and Update a Subscription

Think of the subscription URL as the source for retrieving configuration updates: save the URL, then fetch the configurations from it. Filling out the form and seeing the group name in the list doesn’t mean the configurations have been imported. For your first setup, add just one group and give it a short alias that identifies its source or purpose. You can use that name to find the updated configurations later, instead of checking each entry individually.

v2rayN for Desktop: Add a Group

Open the main window and go to Subscription Group Settings from the Subscription Groups menu. Add a record. Enter an alias, then paste the full link into Optional Address (URL). Don’t include any explanatory text next to the link, and don’t remove anything after the question mark. Save the group and return to the main window. Select the group you just added, then use the subscription menu to choose an option such as Update Current Subscription. Wait for the logs to show the update result, then check that configurations appear in the selected group. If the client offers multiple ways to fetch updates, start with one that can reach the subscription URL over your current network. Don’t rely on a proxy for the first update if you haven’t established a working connection yet.

v2rayNG for Android: Save the URL, Then Update the List

Open the menu in the upper-left corner of the main screen and go to Subscription Group Settings. Tap the plus sign in the upper-right corner. Enter a note or alias, paste the link into the URL field, and tap Save. Return to the configuration list and use the upper-right menu to update subscriptions. If your version lets you update the current group or all groups, switch to the new group first and update that one. When configurations appear, make sure you’re viewing the group you just named, rather than mistaking old entries from another group for the update results.

If the list is still empty, check whether the message indicates a failed request or content that couldn’t be parsed. For a request failure, check that the URL is complete and hasn’t expired, and that the device has network access. For a parsing error, confirm that the URL points to a subscription format supported by the client, not a website login, help page, or share link for a single configuration. If you’re unsure, ask the provider which format to use instead of repeatedly deleting and recreating the group. Subscription URLs may contain access credentials, so when sharing screenshots or logs, include only the group alias and error type. Once configurations are available, move on to choosing which apps will use them.

Choose a Proxy Mode

The configuration list determines which server to connect to; the proxy mode determines which apps send requests through the client. Choose these separately. For a first-time setup, aim to get one familiar app working—not to route all traffic at once. Keep your existing routing rules and DNS settings, and leave the listening ports alone. That way, if the test fails, you can narrow down the issue to the configuration or the traffic scope.

Desktop: Start with the System Proxy

Find System Proxy at the bottom of the v2rayN main window or in the tray menu. Common options include Clear System Proxy, Set System Proxy Automatically, and Do Not Change System Proxy. For the next step, choose Set System Proxy Automatically. This changes the system proxy settings, and only apps that honor those settings will send requests through the client. Do Not Change System Proxy leaves the current value as is; it doesn’t turn the proxy off or undo a previous setting. If your computer already uses a proxy configured by your workplace or school, note the current settings and make sure you’re allowed to change them. Restore the original settings after testing rather than simply clearing them.

For testing, start with a browser that normally follows the system proxy settings. If it has its own proxy configured or is managed by an organization, an enabled system proxy doesn’t mean the browser will use it. Find out which settings your test app follows before changing ports. For now, just choose the mode and test app; enable the system proxy after selecting the active configuration in the next step.

Android: Start in VPN Mode

v2rayNG normally uses the system VPN interface to route traffic. If the settings offer a mode choice, select VPN mode and don’t add per-app rules yet. If per-app settings are already enabled, check that your test app isn’t excluded. Pay close attention to whether the list means “only selected apps use the VPN” or “selected apps bypass the VPN”—the same checkbox has the opposite effect in these two modes. The system may show a connection request when you start. Return to the configuration list and approve it in the next step.

When to Consider TUN

For your first desktop test, don’t enable the system proxy and TUN at the same time. First verify that browser requests work, then configure apps that don’t use the system proxy separately. TUN changes how more traffic is routed, so troubleshooting also involves permissions, routes, and DNS. If you need this mode, set it up and test it separately using the TUN section in the full guide. Don’t switch modes to try to fix a subscription update failure.

Select a Configuration and Connect

Return to the group you just updated and choose a configuration you recognize and that the provider has confirmed is usable. Note its display name, especially if other entries have similar names. Hovering over a row, highlighting it, and setting it as the active configuration aren’t always the same thing. When you check the connection status or logs, make sure you can identify the entry you selected.

v2rayN for Desktop: Set the Active Server, Then Connect

Right-click the target entry in the configuration list and choose an option such as Set as Active Server. If your version lets you set the active configuration by double-clicking, you can do that instead. Check that the indicator or status bar now shows the target entry, then open the system proxy menu and select Set System Proxy Automatically. Next, check the runtime logs in the main window. Confirm that the core started successfully, then verify that the system proxy matches your selection. Opening the client or seeing a highlighted row in the list isn’t enough to confirm either one.

If the logs report that a local port is already in use during startup, first check whether another local proxy is running. Don’t start changing ports in multiple apps. If the configuration isn’t supported by the current core, note the exact error and the type of configuration you selected, then check the provider’s client requirements. If startup hasn’t succeeded, reopening webpages will usually produce the same result. Resolve the startup error before continuing.

v2rayNG for Android: Start from the List and Approve the VPN Request

Tap the configuration you want to use and check that it’s marked as selected, then tap the start button at the bottom. The first time Android shows a connection request, check that v2rayNG is the app requesting VPN access, then approve it. Check that the button shows a running state, then confirm the VPN in the system network status. Some devices show a VPN icon in the status bar; on others, check the system settings. If a VPN managed by your workplace is already active, don’t force a replacement. Check the device management requirements first.

If the button switches to running and then immediately reverts, check the client logs and system notifications. If you denied VPN access, return to the list and try connecting again. If the client reports a configuration error, check that entry instead of changing settings at random. If you try a different configuration, change only that one item, keep the proxy mode the same, and check the running status again. Verify requests only after the process has started: a running status alone doesn’t confirm that the remote server responded or that your test app’s traffic is being routed through the client.

Verify a Request and Restore Settings

Open a service you can normally access and that should use the proxy under your current routing rules. From the test app you selected, send a new request—for example, open a page you haven’t visited before in a new browser tab—and note the time. Don’t rely on a page that was already open before you connected: cached content may still load, and existing connections may continue using the old route. If the client offers a connection test, use it to check the selected configuration, but also send a separate request from the actual app.

Match the Time, Destination, and Outbound Route

Return to the client logs or connection history and look for an entry around that time that matches the destination. If the logs show outbound details, check whether the request went through the proxy or connected directly. A page loading successfully and a matching proxied outbound entry in the client logs confirm that this request followed the expected route. If the matching entry shows a direct connection, first check whether the existing routing rules already send that destination directly. A request that reaches the client and is then routed directly by a rule is different from an app that isn’t using the client at all.

If the page loads but there’s no matching log entry, check whether the current log level records connections, then check the test app’s proxy settings or per-app scope. If the request appears in the logs but times out, focus on whether the current configuration can reach the remote server. If the error is a DNS lookup failure, keep the existing settings and note the failed destination; don’t change the configuration and DNS at the same time. That way, you’ll know which change affected the result when you test again. To understand how routing rules map to outbound routes, read the full guide; there’s no need to rewrite rules during your first setup.

Disconnect and Test Regular Internet Access

After desktop testing, select Clear System Proxy before closing the client, then check whether the system proxy settings match their original state. If you had a manual proxy before testing, restore it using your notes. On Android, return to the configuration list, tap Stop, and confirm that the system shows the VPN as disconnected. On either platform, send a fresh request from a regular app to compare. If access fails after closing the desktop client, check whether the system still points to the stopped local proxy. On Android, check for another always-on VPN or a system policy that blocks connections when the VPN disconnects.