This guide is for anyone setting up v2rayN on Windows or macOS for the first time. First, make sure the client and core start correctly. Then import a subscription, select a node, and check the listening port. Finally, enable the system proxy and test it with the same app before and after. If something goes wrong, identify which step failed before changing the relevant setting.
Download, Extraction, and Runtime Requirements
Choose a download for your operating system and processor architecture. x64 is for 64-bit Intel or AMD processors; ARM64 is for Windows on ARM or Macs with Apple silicon. A 64-bit operating system does not necessarily mean the processor is x64. The examples below use the commonly seen v2rayN 7.x interface; menu labels and locations may vary slightly by version or build.
- Windows: Open Settings → System → About and check System type. Extract the entire archive to a writable location, such as
D:\Tools\v2rayN, then runv2rayN.exe. Don’t launch the app from the archive preview or drag only the main executable to your desktop: configuration files and bundled cores may need to be loaded from the original folder. - macOS: Open the Apple menu → About This Mac and check Chip or Processor. Choose ARM64 for Apple silicon and x64 for Intel. If you downloaded a disk image, open it and follow the included instructions to move the app to Applications. If you downloaded an archive, extract it fully before moving the app. If macOS displays a security warning, verify the download source and read the warning; don’t disable system-wide protections just to launch the app.
- Runtime requirements: If Windows reports that .NET is missing, check the framework name, major version, and architecture in the message. For example, if it specifically requires x64
Microsoft.WindowsDesktop.App 8.0, install the x64 .NET Desktop Runtime 8.0—not just the standard runtime. Self-contained builds typically don’t need the corresponding .NET runtime installed separately. Seeing the main window open also doesn’t mean the proxy core has started.
Choose a Core That Matches Your Node
v2rayN is a desktop client; the proxy core reads node configurations and establishes connections. Choose a core based on the node’s actual protocol, transport, and security settings—not the subscription group’s name. For example, VLESS is a protocol and REALITY is part of the security configuration. Neither is a core option.
Two Options for a First Install
Xray Core
RecommendedIf the server specifies VLESS, REALITY, and Vision flow control, use Xray as required by the server. Preserve the original fields after importing the configuration; don’t manually change a standard TLS node into a REALITY node.
Best for: Nodes that explicitly require Xray, or configurations that rely on Xray-specific features.
V2Ray Core
If the provider specifies V2Fly’s V2Ray core, check the protocol and transport against its documentation. VMess over WebSocket with TLS doesn’t automatically require switching cores. Consider switching only if the client offers that option, the core is ready, and the configuration is supported.
Best for: Nodes with explicit V2Ray core instructions from the provider that you need to follow.
Import a Subscription and Enable the System Proxy
A subscription URL retrieves a list of nodes; it isn’t the same as a link for a single node. Have the subscription URL and group name from your provider ready. For the first test, select just one node and leave DNS, routing, and TUN settings unchanged. This makes it easier to identify the cause if an error appears in the logs.
From an Empty List to a Connection Test
Add a Subscription Group
In the main window, open Subscription Group → Subscription Group Settings, add a group, enter a name and subscription URL, then save. Some versions have a + button in the group bar. Make sure you paste the full URL, including any parameters after the question mark. These parameters may contain access credentials, so don’t include them in public screenshots.
Update the Subscription
Select the new group and find the Update Current Subscription option in the Subscription Group menu. If you don’t have a working proxy yet, choose the option to update without a proxy. Return to the group after the update and confirm that nodes appear in the list. A successful update only means the client retrieved and parsed the list; it doesn’t confirm that any node can connect.
Set an Active Node
Right-click a node in the list and choose Set as active server. Confirm that the active node shown in the main window matches your selection. To check the default core, go to Settings → Parameter Settings → Core Type Settings and review the setting for the relevant protocol. If your version lets you assign a core to an individual node, check that setting too.
Check the Local Listener
Check the main window’s status bar and logs, then go to Settings → Parameter Settings to review the local listener settings. If the mixed port is shown as
10808, check that port in the next steps; otherwise, use the value displayed. If the logs show a port conflict or core startup failure, fix the listener before enabling the system proxy.Enable the Proxy and Test It
In the system tray menu or the main window’s System Proxy menu, choose Set system proxy. Open a test page in a browser that follows the system proxy settings, and check the client logs for the corresponding request. If the page loads both before and after the change, check the routing result too: a request appearing in the logs doesn’t necessarily mean it was routed through the active node.
Check the Local Port and System Proxy
The local listening address is where apps send requests to v2rayN. The server address and port in a subscription are used by the core to connect to a remote server. Don’t use one in place of the other. For your first setup, keep the listener local and leave Allow connections from the LAN turned off.
Settings to Check
Client listener
- Local address
127.0.0.1- Example mixed port
10808; use the value shown in the app- LAN access
- Off
- Error clue
address already in usemeans the listening address and port are already in use
A mixed port accepts both HTTP and SOCKS requests. If the app lists separate ports, enter the one that matches the proxy type you selected.
System Proxy
- Check on Windows
- Settings → Network & internet → Proxy
- Check on macOS
- System Settings → Network → Current network service → Details → Proxies
- Browser test
- Use the system proxy settings; don’t also enable separate proxy rules in the browser
- Before you quit
- Choose Clear system proxy in the client, and restore any settings you recorded earlier if needed
The system proxy only affects apps that follow it. Clear it before quitting to prevent apps from sending requests to a local port that is no longer active.
Common Problems: Diagnose by Symptom
Note the time of the failure, active node, and local port, then reproduce the issue once. Check three things separately: whether the subscription downloads, whether the core is listening, and whether the app’s requests are being sent as expected. Change one setting at a time and test the same page in the same app to see whether the change helped.
First-Time Setup FAQ
The subscription update succeeded, but why is the list still empty?
Select the group you just updated and clear any list search filters. Then check whether you updated the intended group or a different one. If the logs show a parsing error, ask the provider to confirm that the URL returns a subscription format supported by v2rayN, not a login or account page. Share only a redacted error report.
The subscription update timed out. Should I switch to updating through the proxy?
First, confirm that your current network can open a regular web page, then check the subscription URL and client logs. If you already have a verified, working active node, try updating through the proxy and compare the results. If you’ve just installed the client and don’t have any nodes yet, changing the update method won’t create a proxy connection. Ask the provider how the URL can be accessed.
A port is already in use. Can I change it to 10818?
First check whether another instance is running. Quit the old instance normally and try again. If another app needs the original port and 10818 is available, change the mixed port to that value and reload the core, then have v2rayN reapply the system proxy. Update any apps where you previously entered the port manually, or they’ll keep connecting to the old one.
The page says the connection was refused. Is the node down?
First, check which address the error refers to. If the connection to 127.0.0.1:10808 was refused, check whether the core started and whether the app’s port matches the current listener. If the client received the app’s request but the logs show a remote connection failure, check the node address, port, and current network. Don’t mistake a local listener error for a remote server problem.
Why does my browser lose internet access after I quit v2rayN?
Check whether the system proxy still points to a local port, and whether a proxy is manually configured in the browser. If the leftover settings were added for this test, reopen the client, choose Clear system proxy, and quit again to verify. If your computer already had proxy settings from work or school, restore the settings you recorded before testing instead of overwriting them.