v2rayN First-Run Setup Checklist for Windows and macOS

Avoid common first-run issues with v2rayN on Windows and macOS. Check the extracted files, runtime requirements, launch permissions, local ports, and core selection.

At a glance

Setting up v2rayN on Windows or macOS for the first time? Verify three things in order: the main window opens, the selected node can send requests through the local proxy, and your browser picks up the system proxy settings. Don’t move on until each step works. This makes it easier to pinpoint whether a crash, empty subscription, or browser connection issue is coming from.

Installer files, extraction folder, and first-launch permissions

First, distinguish the desktop client from the proxy core. If double-clicking the app doesn’t open the main window, check the package, runtime requirements, and system alerts. If the window opens but the log reports an error after you select a node, check the core files, node settings, and ports. Menu names below are based on the common Chinese-language interface in v2rayN 7.x; labels and button locations may vary between minor versions.

Import a subscription and test one node first

Adding a subscription URL only saves the update source; it doesn’t mean the nodes have been fetched successfully. For your first setup, use one source and one node, and test subscription updates, core startup, and the system proxy separately. Subscription URLs may contain account tokens, so hide the full URL in screenshots and check that it isn’t printed in the logs.

  1. Add a subscription group

    In the main window, open Subscription Group → Subscription Group Settings, then click Add. Enter a label that helps you identify the source, paste the full subscription URL into the optional URL field, and save. If you have a single share link starting with vmess:// or vless://, use the clipboard import option under the Servers menu instead of entering it as a subscription URL.

  2. Update the current group

    Return to the main window, select the new group, and choose Update current subscription from the Subscription Group menu. For the first update, you can try the option that doesn’t use a proxy. Check the log to see whether the update succeeded, then confirm that nodes appear in the group. A successful update only means the list was retrieved; it doesn’t confirm that any node can connect.

  3. Set an active node

    Right-click a known working node in the list and choose Set as active server. Clicking a row usually only selects it; that alone doesn’t mean the core has switched. After switching, check the current node shown in the main window and the log for core startup failures or port binding errors.

  4. Check the local port

    Open Settings → Parameter Settings and find the local listening port under v2rayN Settings. Note the actual value, then use the explicit proxy request below to test it. Don’t switch nodes, change routing rules, or enable TUN at the same time; otherwise, it’ll be harder to tell what caused a failed request.

Choose a core based on the node settings

v2rayN is a desktop client; Xray and V2Ray are cores that handle connections. Go to Settings → Parameter Settings → Core Type. The core is generally selected based on the configuration type—it doesn’t convert every node to a single protocol. After importing a subscription, keep the original settings first. Check the core selection and version only if the log explicitly reports an unsupported configuration.

Xray core

Recommended

For a VLESS + REALITY configuration, use Xray if that’s what the server documentation recommends. The transport, security options, and Flow must match the server. If the node has no Flow value, don’t add one just to match an example. If an option isn’t recognized, check the log to see which core started and which version it’s running.

Best for: subscriptions that specify VLESS + REALITY or server instructions that require Xray.

V2Ray core

If this option is available in your client and the administrator has provided a compatible V2Ray version and VMess configuration, select it as instructed. For VMess + WebSocket + TLS, keep the path and server name exactly as provided. Switching to the V2Ray core won’t fix an incorrect path or certificate name.

Best for: connecting with an existing V2Ray server configuration and explicit setup instructions.

Test the local listening port separately from the system proxy

The server port in a node’s details is for the remote connection. The port used by your browser or terminal is a local listening port—these are different settings. The examples below use 10808: run them as written only if Parameter Settings and the log confirm that this port accepts HTTP proxy requests. If it’s a SOCKS-only port, use the test on the right instead. During initial troubleshooting, keep access local; don’t enable “Allow connections from the LAN.”

HTTP or mixed listener

Local address
127.0.0.1
Example port
10808, replace with the actual HTTP or mixed port
Proxy address
http://127.0.0.1:10808

Even when the destination uses HTTPS, a standard local HTTP proxy URL still starts with http://.

SOCKS listener

Local address
127.0.0.1
Example port
10808, replace with the actual SOCKS or mixed port
Proxy address
socks5h://127.0.0.1:10808

This is the syntax curl recognizes for resolving the destination hostname through the proxy. Don’t enter it in the system’s HTTP proxy field.

Keep the system proxy off and TUN disabled, then send a regular webpage request through the explicit proxy. In Windows PowerShell, use curl.exe; in macOS Terminal, replace the command at the start with curl. The 5-second connection timeout and 15-second total request limit are diagnostic limits for this test, not performance benchmarks.

curl.exe --proxy http://127.0.0.1:10808 --noproxy "" --connect-timeout 5 --max-time 15 -I https://example.org/

Common first-run setup problems

Subscription update times out and the node list is still empty?

Check the log to see whether the failure is in DNS resolution, the connection, or the subscription server’s response. Make sure the URL was pasted correctly and the right group is selected. If the server returns 401 or 403, ask your subscription provider to verify your token and access permissions. If the connection times out and you already have a confirmed working node, try updating through the proxy. Without a working node, repeatedly switching this option won’t establish a connection.

Why does the browser work but the terminal still connect directly?

Your browser may use the system proxy, but terminal apps don’t necessarily use the same settings. First, set a proxy for a single request with the --proxy option above. If that works, check whether your tool supports HTTPS_PROXY and whether NO_PROXY excludes the destination. Don’t start by adding these variables to your global startup configuration.

Why did my subscription and settings disappear after restarting?

Check the shortcut’s target path to make sure you haven’t opened a different extracted copy. Close the client, keep the current version in one fixed, writable location, then reopen it, change an easy-to-recognize setting, and restart to see if it persists. If the log reports a write failure, fix the folder permissions or move the app to a location your account can write to.

After I quit, no apps can open webpages. Do I need to reinstall?

Check whether the system proxy still points to a listening port on 127.0.0.1 that’s no longer active. If the client starts, use Clear system proxy before quitting. If it won’t start, undo the values changed during this test in your system’s proxy settings. If you use a work network preset, restore the settings you noted earlier; don’t clear other proxy entries.

Download v2rayN