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.
- On Windows, check your system type first. Open Settings → System → About and look under “System type.” Most 64-bit Intel or AMD PCs should use x64; for ARM devices, choose a package that matches your system architecture. Extract the entire archive to a fixed folder your account can write to, such as
%LOCALAPPDATA%\Programs\v2rayN. Don’t launch the app from the archive preview or move the executable on its own—the accompanying core and dependency files must stay with it. - Use the launch prompt and package notes to determine runtime requirements. For example, if a Windows WPF package explicitly requires
Microsoft.WindowsDesktop.App 8.0, install the .NET 8 Desktop Runtime that matches the app’s architecture. The standard .NET Runtime 8.0 is not a substitute for the desktop runtime, and installing a different major version won’t meet the requirement. If the package already includes its runtime, follow its instructions and try launching it before installing anything else. - On macOS, check the chip, then the app’s location. In the Apple menu, choose About This Mac. If it lists an Apple chip, choose arm64; if it lists an Intel processor, choose x64. For a disk image, follow the included instructions to copy the app to Applications, then launch it from there. If you downloaded an archive, extract it fully first. Don’t keep running the app from a mounted disk image or your Downloads folder.
- Use the alert details to tell a security block from a permissions issue. If the system displays a security warning, first verify the download source, system version, and package type. Then check the specific reason in Windows Security’s Protection history or macOS System Settings → Privacy & Security. If the app is reported as damaged or malicious, don’t launch it; verify the source again. If the log only says the configuration folder isn’t writable, move it to a writable location rather than running as administrator every time.
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.
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://orvless://, use the clipboard import option under the Servers menu instead of entering it as a subscription URL.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.
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.
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
RecommendedFor 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/
- Connection refused: Make sure the client is still running and the port is correct, then check the log for a listener failure. If you see
address already in use, close any leftover client instance or change the local port to one you’ve confirmed is free. Apply the change and test again using the new port. - You only see
200 Connection established: That’s the proxy’s response to CONNECT, not the destination webpage’s final response. Check whether an HTTP status from the destination appears next. If the handshake fails or times out, check the core log for the same request for node connection or certificate errors. - You’ve received a response from the destination: This confirms the request reached the local proxy, but not necessarily that it went through a remote node. Routing rules may send the test domain directly. To verify node traffic, use a test domain that should be proxied under your current rules, then check the core log to confirm the matched outbound.
- Turn on the system proxy only after the explicit request works: Select Set system proxy in the tray or status menu, then reopen your browser and test again. On Windows, check Settings → Network & Internet → Proxy. On macOS, check System Settings → Network → select your current network service → Details → Proxies. Note the original values first. After testing, select Clear system proxy in the client and restore the previous settings if needed.
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.