V2Ray Setup Guide
Import subscriptions and test your connection

Before you begin: check the client and subscription URL

Install the client for your device before following the steps below. Use v2rayN on desktop and v2rayNG on Android; find the download links on the client downloads page. When you open the app, you should see a server list or an empty main screen. If the app won't start properly, troubleshoot its runtime requirements, folder permissions, or installation first instead of repeatedly changing the subscription URL.

Get your subscription URL from a trusted service provider. The client reads the configuration and connects to servers; installing it does not provide servers automatically. A subscription is usually a full URL, while a share link may start with vless:// or vmess://. They use different import methods: add a subscription URL to a subscription group, or import an individual server from a share link, usually via the clipboard. Identify what you have before choosing an import method.

Copy the full URL, including its path and query parameters. Don't include extra spaces, line breaks, or surrounding text. Subscription URLs may contain account credentials, so don't post them in public forums or leave them visible in screenshots. Start by importing one group and one server; once you've verified the connection, add other groups as needed. This makes problems easier to isolate.

Step 1: Import a subscription

v2rayN: Add and update a subscription group

In the v2rayN top menu, open Subscription Group, then Subscription Group Settings, and add a group. Give it a recognizable name and paste the full subscription URL into the address field. The name is only for organizing groups locally; it doesn't change server connection settings. Leave the other options at their defaults for now, save, and return to the main screen.

From the Subscription menu, choose an update option and select the group you just added, or update all subscriptions. The client will request the URL and parse its server entries. When the update finishes, open the group to view its list. A successful import shows server details such as names, protocols, and addresses—not just the group name. Adding a group saves the URL; updating it fetches the server configurations.

For the first update, try an option such as Update without proxy. Use Update through proxy only if you already have a working proxy connection and the subscription URL requires it. Trying to update through a proxy before importing any usable server can create a dependency loop. If the request times out, check your network and whether the URL is reachable. If parsing fails, make sure you copied a subscription format the client supports.

v2rayNG: Add a subscription from the side menu

Open the v2rayNG side menu, go to Subscription Group Settings, and tap the add option. Enter a label and subscription URL, save, then return to the main screen and choose Update subscriptions from the top-right menu. If your version offers separate options for the current group and all groups, update the new group first. When the update finishes, imported servers should appear as cards on the main screen. If the list is filtered by group, switch to the correct one.

If you have a single share link rather than a subscription URL, copy it and use the add option on the main screen to import from the clipboard. This saves one server configuration; it does not create a subscription group that can be refreshed automatically. If the server settings change, you may need to import the link again. Don't enter a share link as a subscription URL.

You're ready to continue when the target group contains a selectable server. Don't change transport, security, or identity fields yet; these settings are included in the subscription, and changing them arbitrarily may prevent the connection from working. See the subscription terminology guide for the difference between subscriptions and share links. If the update fails, see how to troubleshoot failed subscription updates. Once the list looks right, configure how traffic reaches the client.

Step 2: Choose a proxy mode

Keep two questions separate: how app traffic reaches the client, and which route handles it afterward. System proxy and TUN mode mainly determine how traffic enters the client; routing options such as Global or Bypass LAN determine where matching traffic goes. A global route does not automatically make every app use the system proxy. For your first setup, choose one simple, testable traffic path rather than enabling multiple interception methods at once.

v2rayN: Start with the system proxy

On desktop, open the System Proxy menu; in some versions, you can also right-click the tray icon. When you're ready to connect, choose Set system proxy or the equivalent option in your version. This directs the system proxy to the local port used by the client. To test, use a regular browser that follows system proxy settings—not a game, command-line tool, or app with its own proxy settings.

Next, open Routing or Routing Settings and start with a built-in profile. For everyday use, choose a profile that matches your needs, such as one that bypasses LAN addresses. To check whether routing is causing an access issue, you can temporarily switch to a global proxy route, compare the results, and then restore your original setting. Profile names and rules vary by version, so don't assume a name alone tells you how every domain will be routed.

Leave TUN disabled for now. TUN can handle traffic from apps that don't follow the system proxy, but it involves a virtual network interface, permissions, and compatible core settings; it's not required for your first connection. If you need it later, see the TUN mode configuration guide. For rule matching order, see the routing configuration reference.

v2rayNG: Check VPN and per-app settings

On Android, the client usually handles traffic through its own local VPN service. Open Settings and check the routing options, starting with the defaults or a familiar built-in profile. If you've configured per-app proxying, make sure your test browser isn't excluded. For the first test, disable per-app restrictions and confirm the connection works; then choose which apps to proxy one by one.

Android's VPN service and the desktop system proxy are separate traffic entry points. Don't copy desktop proxy port settings into your phone's Wi-Fi proxy settings. If another app on the device is using the VPN service, stop it first to avoid competing for the system connection. Once these checks are done, the traffic path is clear: select a server and connect.

Step 3: Select a server and connect

v2rayN: Set the active server

Return to the v2rayN server list and select the server you want to use. Choose Set as active server from the right-click menu, or use the equivalent option in your version. Some versions also let you double-click a server to activate it. What matters is that the interface shows it as active—not just that the row is highlighted. Then make sure the system proxy is enabled; selecting a server and routing system traffic through it are separate actions.

Check the log panel at the bottom or open the log view. The core should start normally, without persistent errors such as a port conflict or failed configuration parsing. If the listening port is already in use, check whether another client instance is running and close the duplicate before trying again. Don't enter different port numbers in the app, client, and system settings; even if the core starts, app requests may not reach it.

If the logs show connection failures, first make sure the active server belongs to the group you just updated, then try another server from the same subscription. Retry the same request and check the new logs. Latency tests can help you compare servers, but a successful test only confirms that its test path responded—it doesn't prove your browser used that server. A failed test may also be caused by the test address or method.

v2rayNG: Connect and approve the VPN request

On the v2rayNG main screen, tap the server you want to use and confirm the selection indicator moves to it. Then tap Connect. The first time you connect, Android will show a VPN connection request. Check which app initiated it and approve the request. If you denied it, the client can't route traffic through Android's VPN service; tap Connect again and follow the system prompt.

After connecting, check that the button shows a running state and that Android displays a VPN indicator. The indicator confirms the local service is active, but doesn't by itself prove the remote server is reachable. Check the app logs or use its connection test, then verify with an actual request. Some Android versions restrict background activity. If the connection drops only when the screen is off, first check whether background limits are the cause, then adjust the app's battery settings as needed. There's no need to change every system permission in advance.

If the connection stops immediately, check the current error before reinstalling. A configuration error, an unapproved VPN request, and a remote connection timeout require different fixes. Note the error type, the step where it occurred, and which server was selected. Before sharing logs, redact the subscription URL and any identifying details. If protocol and transport terms are unfamiliar, consult the protocol terminology guide; you don't need to enter a manual configuration to get started.

Step 4: Verify the connection

Check the connection at three levels: the client is running, the test app is sending requests through it, and the remote request gets the expected response. A green button, VPN indicator, or latency reading alone can miss the middle step. Keep the current server and mode unchanged, open a reliable test page suited to your network in a browser, and confirm that it loads fully.

Cross-check a real request against the logs

In v2rayN, make sure the system proxy is enabled, open a new browser tab, and load a page while checking the logs. If your current log level records access, you should see the destination or a connection entry. If your version has a connection view, check the request's outbound route there too. If the logs show an attempted connection but the page won't load, the issue is more likely with the remote connection or name resolution. If no related request appears, first check whether the browser follows the system proxy.

In v2rayNG, leave the client connected and use a browser that isn't excluded by per-app rules to open the same page. Return to the client to check its connection test and logs. If the browser has its own proxy settings, restore its normal system network settings first to avoid adding another manually configured proxy. Low log levels may not record individual requests, so the absence of a log entry alone doesn't prove the request never reached the client.

For an additional check, use a trusted public IP lookup page and compare the results before and after connecting. Only requests routed through the proxy should show its exit IP. If the lookup domain is routed directly, an unchanged result doesn't mean the client has failed. You can temporarily switch to a global proxy route to compare, then restore your original profile. Browser cache and existing connections may affect the results; if needed, close the test tab and open a new one.

If it fails, check each part of the traffic path

If no pages load, disconnect the proxy and confirm your regular network connection works. If it does, check the active server, client status, and traffic entry point. If only certain sites fail, check their routing and error logs instead of replacing the entire subscription. For DNS errors, see the DNS configuration reference. Avoid changing DNS, servers, and proxy modes all at once, or it will be difficult to identify the cause.

If a desktop browser works but a particular app still uses the regular network, that app probably doesn't follow the system proxy. Check the app's own proxy settings and whether it supports a local proxy, including the actual listening port. Consider TUN only if you need to handle more of the app's traffic. If one Android app has a problem, review the per-app list and the app's own network behavior. Change one setting at a time and repeat the same test request to see whether it helped.

Disconnecting and what to configure next

When you're done on desktop, choose Clear system proxy from the System Proxy menu before quitting the client. Otherwise, some apps may keep sending requests to a local port that is no longer listening, leaving them unable to connect. On Android, tap Stop and confirm the VPN connection has ended. If the VPN indicator remains, check the status in the client or Android VPN settings.

Once all four steps are verified, enable automatic updates for subscription groups if needed and organize your servers and routes to suit your setup. The client may overwrite manual changes the next time it updates a subscription, so check where settings are managed before making long-term customizations. See the subscription configuration guide and system proxy configuration guide for how subscriptions, system proxy settings, and core fields fit together. This completes the initial connection setup; consult the configuration reference for the full JSON structure and field descriptions when needed.