v2rayN Tutorial

This tutorial assumes that the client is already installed and that you have a subscription URL from a known source that has not expired. The service provider generates the URL; the client does not create it automatically. v2rayN or v2rayNG reads the configurations in the URL and passes them to the appropriate core to establish a connection. If you only have a single share link, you can use the client's “Import from Clipboard” feature, but do not mistake one link for an updateable subscription group.

Before configuring the client, close any other programs that are changing the system proxy or establishing a VPN connection. When multiple tools run at once, the browser may use an old proxy and system routes may be overwritten by whichever program starts last. Temporarily closing them does not mean they can never coexist; it simply leaves one variable during the first test. Also verify that the device date, time, and time zone are correct. TLS or REALITY parameters may be affected by clock drift.

Before changing anything, note the current network state: whether the system proxy is enabled, whether the browser uses a separate proxy, and whether DNS is manually configured. Do not change routing rules, DNS, TUN, and core parameters all at once. After basic connectivity is verified, adjust them one at a time as needed. For platform-specific installation paths, permissions, and architecture choices, see the common preparation section in the all-platform guide.

Add a Subscription in v2rayN Desktop

Copy the complete subscription URL, taking care not to include spaces or line breaks automatically added by a chat app. Open the v2rayN main window, find “Subscription Groups” or a similarly named subscription management entry in the top menu, and open the subscription group settings. Add a record, give it a recognizable remark, and paste the URL into the URL field. The remark is only for local identification and does not change connection parameters.

After saving, return to the main window, open the subscription menu again, and choose “Update All Subscriptions” or update the group you just added. Normally, the main list will show the servers in that group after the update. Check that the list actually changed and that basic fields such as the server name and type are visible. “Saved successfully” does not mean the subscription content was downloaded; the update must still be completed.

Add a Subscription in v2rayNG on Android

Open v2rayNG and go to subscription settings, then use the add entry in the upper-right corner to create a subscription. Enter a remark, paste the URL, save it, return to the subscription list, and run an update. Menu wording may vary slightly between versions, but the required actions remain the same: save the URL and actively update it. After a successful update, return to the configuration list and look for the newly imported entry.

If the clipboard contains a single vmess, vless, or other share link, choose “Import from Clipboard” from the upper-right menu. A single-link import usually creates one local configuration and will not update in bulk like a subscription. For long-term management of multiple servers, use subscription management; use clipboard import for temporarily testing one set of parameters.

What to Check When No Servers Appear After an Update

Reopen the subscription settings and make sure the URL was not truncated and that the remark was not pasted along with it. Run the update again and check the notification or log. A request failure usually means the problem occurred while accessing the subscription URL; a parsing failure may mean that the returned format is not recognized by the current client. Do not keep creating identical groups, or duplicate servers will make troubleshooting harder.

Also distinguish between “subscription update succeeded” and “the server can connect.” A successful update only means that the client read and parsed the configuration; it has not verified the remote address, port, protocol parameters, or network path. Once the server list appears, do not rush to change DNS or routing. Move directly to choosing a proxy mode. For system guidance on managing subscription groups, removing duplicates, and handling update failures, see Configuration FAQs.

Start with System Proxy on Desktop

For most first-time v2rayN desktop users, System Proxy is easier to observe and troubleshoot. It writes the proxy address to the operating system settings, which browsers and other apps that follow system settings generally use. Open the v2rayN “System Proxy” menu and choose “Set System Proxy” or the equivalent option in your version. You may also see “Clear System Proxy” and “Do Not Change System Proxy”; these remove the current setting or leave the system state unchanged.

System Proxy does not guarantee coverage for every app. Some programs use their own network stack, some games and command-line tools ignore system settings, and some browsers may have a separate proxy configured. If one app has no traffic, you cannot conclude that it is covered simply because other pages open. Verify the browser first, then decide whether TUN is needed for the app range you want.

Consider TUN Only When You Need Broader Coverage

TUN handles traffic through a virtual network interface and usually covers more apps than System Proxy, but it also adds permission, routing, and DNS requirements. Before enabling it, confirm that v2rayN can run with the required permissions and note the existing System Proxy state. When switching to TUN for the first time, clear System Proxy first, then enable TUN so two entry points do not obscure the actual traffic path.

If local network access breaks immediately after enabling TUN, do not keep changing DNS or routing rules. Turn TUN off first and confirm that the network recovers, then check the log for failures creating the virtual interface, obtaining permissions, or writing routes. For complete guidance on virtual-interface permissions, LAN access, and routing boundaries, see the Windows installation and configuration section or the Linux installation and configuration section.

Confirm System Permission on Android

v2rayNG requests system VPN permission when it starts a connection. The first time the permission dialog appears, confirm it before traffic can be handled. If you decline, the client may retain the server configuration but cannot send app traffic through the connection. If another VPN is already active, stop it before starting v2rayNG, because the system generally allows only one such connection at a time.

Configure app routing, LAN bypass, and routing rules after basic connectivity works. For the first test, keep the rules simple so a domain allowed by a direct-connection rule is not mistaken for a failed server. Choose a mode based not on which feature list is longer, but on whether the app follows the system proxy, whether more protocols need to be handled, and whether the device can provide the required permissions.

Select a Configuration

In the v2rayN main list, click the server you want to use, then use the context menu or double-click to set it as the active server. Depending on the version, a color, bold text, or status-bar message may indicate the current selection. Afterward, check the bottom of the main window or the tray menu and confirm that the active server name matches your choice. Highlighting a row without setting it as active may leave the previous configuration in use.

In v2rayNG, return to the configuration list and tap one entry. The selected item usually shows a selection marker. Then tap the start button on the main screen and wait for the VPN indicator to appear in the system status bar, while checking that the in-app status changes from stopped to started. The start button uses the currently selected configuration, so verify the server name before tapping it.

A Connection Test Is Not the Same as Real Access

The client may offer a connection test, real-connection test, or download test. A basic latency test may only check reachability and cannot fully represent the protocol handshake or subsequent access. A real-connection test is closer to an actual connection, but still cannot prove that every app is using the correct proxy entry point. Tests narrow down the possibilities; they do not replace browser and log verification.

For the first test, run a real-connection test on a small number of servers and choose one with a normal result. Do not repeatedly test a large list or judge configuration quality by latency alone. Usability also depends on protocol parameters, TLS or REALITY settings, remote status, and the current network path. Keep the selected server unchanged and continue with real-access verification.

When the Connection Fails, Read the First Key Error

If the client stops soon after starting or the log keeps showing errors, record the earliest important message first. DNS resolution failure, connection timeout, connection refusal, TLS handshake failure, and parameter mismatch point to different stages of the problem. Do not pick a repeated message at the end of the log at random; later retries may simply be consequences of the same issue.

Keep the troubleshooting sequence simple: confirm that the intended server is selected, update the subscription once, then test another configuration from the same group. If several configurations fail at the same stage, check the local time, network, and client permissions. Change one condition at a time and reconnect after each change so you can identify what made a difference.

Start with a Minimal Browser Check

Keep the selected server and proxy mode unchanged. Fully close the test browser, reopen it, and visit a page whose loading result is easy to judge. Restarting the browser reduces interference from old connections, cached data, and separate proxy settings. If the page loads normally, open the client log and check whether a new connection record appears at the same time.

The log usually shows the target domain or address, the routing result, and the connection process. When the browser request and log timestamp match, you can reliably confirm that browser traffic entered the client. If the page opens but no new log entry appears, the browser may have connected directly, used its own proxy, or been allowed through by a routing rule. Check the browser network settings and client routing before changing servers.

Then Verify the App You Actually Need

After browser verification succeeds, open the app you actually need and observe the log again. In System Proxy mode, if the browser appears in the log but the target app does not, the app usually does not follow the system proxy. Check whether it offers its own proxy settings, or switch to TUN after confirming the required permissions and routing conditions. Disable the existing interception method before switching so the result remains clear.

On Android, open a page first, then return to v2rayNG and check whether live logs or connection statistics changed at the corresponding time. If app routing is enabled, confirm that the test app is not configured to bypass the proxy. If only one app fails while others create connection records, first inspect that app's routing rule, background restrictions, and network settings; there is no need to immediately re-import the subscription.

Rule Out DNS and Cache Interference

Sometimes the connection is established but the page still fails because of DNS resolution or stale cache. Test another domain first, then try closing and reopening the app. Do not change system DNS, client DNS, and browser Secure DNS at the same time before identifying the cause; even if the issue disappears, you will not know which layer helped. For a system-level explanation of DNS query paths and rule matching, see Configuration FAQs in the all-platform guide.

The final assessment should meet three conditions: the client remains running, the target app creates a corresponding log entry, and the page or service completes a real request. Basic setup is complete only when all three are true. A successful server test means the configuration may connect; a running client only means the process started; a page that opens without a log entry requires checking whether it was a direct connection.

Keep the verified server and proxy mode for now, and give the subscription group a recognizable name. If duplicate groups were created during import, delete the extras after confirming that their contents match. Do not delete the only working configuration and then try to recover it, and do not mix subscriptions from multiple sources into one indistinguishable group.

When you finish using the client, exit according to the active mode. With System Proxy, choose “Clear System Proxy” in v2rayN before exiting so the system does not retain an unusable local proxy address. With TUN, turn off TUN and confirm that the network recovers before exiting. On Android, tap the stop button in v2rayNG and wait for the system VPN indicator to disappear.

When you later configure LAN bypass, domain-based routing, custom DNS, startup behavior, or rule database updates, handle one topic at a time and repeat the “real access plus matching log entry” check after each change. Platform-specific installation permissions, TUN requirements, known issues, and recovery steps are covered in the all-platform installation and configuration guide.

If the client is not installed yet, open the client download page and choose an installation entry for your platform. On desktop, start with v2rayN; on Android, choose the appropriate client based on the core and your needs. After installation, return here and begin with subscription import.