Setting up v2rayN on Windows or macOS for the first time? Choose the right package and make sure settings persist. Then import a node or subscription from a trusted source, enable the system proxy, and test it in your browser. If something goes wrong, check in this order: does the app launch, is the core listening, and is the app using the proxy? Change one thing at a time.
Choose the right package: check your processor and runtime requirements
v2rayN is a desktop client for managing configurations. Connections are established by the core it launches, such as Xray. An open window only confirms that the client started. If the package doesn't include the required core, or your system blocks it from running, connections may still fail after you select a node.
Before you install v2rayN on Windows or macOS
Windows
- Go to Settings → System → About and check System type. Choose the x64 or ARM64 package that matches.
- If you're using an archive, extract all of it to a permanent folder you can write to, such as
%LOCALAPPDATA%\v2rayN, then runv2rayN.exe. Don't drag only the main program to your desktop or launch it from the archive preview. - If a startup message says .NET is missing, install the runtime version and architecture specified in the message and package notes. If the classic WPF build specifically requires
Microsoft.WindowsDesktop.App, install the .NET Desktop Runtime, not the standard .NET Runtime.
macOS
- Open About This Mac from the Apple menu. Choose ARM64 for an Apple chip or x64 for an Intel processor.
- Extract the release archive or open the disk image, then move
v2rayN.appto Applications before launching it. Don't use a mounted disk image as the app's permanent home. - If macOS blocks the app, read the warning and verify the package source and architecture first. Only if you trust the source and macOS offers a one-time approval option for this launch, go to System Settings → Privacy & Security to allow it. Don't disable system-wide security checks.
Start the app without elevated privileges. If you encounter a specific runtime or file-write error, follow the message's instructions instead of treating administrator access as the default fix.
First-time setup: import a node and test your browser
A node is a server connection configuration; a subscription uses a link to fetch a list of nodes. Start by importing just one source to make it easier to tell whether a subscription failed to load or an individual node is unavailable. The steps below use common menus in the Chinese interface of v2rayN 7.x. Button labels may vary slightly between builds.
Make sure settings are saved
Go to Settings → Parameter Settings and make sure the window opens. After importing, exit normally and reopen the app to check that your groups are still there. If they disappear every time, check whether the app is running from a temporary folder and look in the logs for configuration write errors.
Import one source
For a subscription link, go to Subscription Groups → Subscription Group Settings, add a group, enter a recognizable name and the subscription URL, then save. Back in the main window, select that group and try Subscription Groups → Update current subscription (direct) first. For a single node link, copy it and use Servers → Import share links from clipboard. Don't paste a node link into the subscription URL field.
Enable a node and check the logs
Right-click a node in the list and select Set as active server; some builds also let you double-click to switch. Check the log area in the main window for core startup or listening errors before continuing. A node appearing in the list only means its configuration was imported, not that the remote server is reachable.
Enable the system proxy
Open System Proxy from the client menu and select Automatically configure system proxy. The system proxy is a set of proxy settings provided by the operating system for apps that support them; it doesn't route every program. For your first test, leave TUN (virtual network adapter mode) off and keep the existing routing rules to avoid changing both traffic handling and routing behavior at once.
Compare the webpage with the logs
Open a new page in a browser that follows system proxy settings and visit an HTTPS site you can normally reach. Check the core logs for the same time. A page loading doesn't prove the request went through the remote proxy: routing rules determine whether traffic connects directly or uses the proxy. If the log says direct, it only confirms that the direct route worked.
Local port conflicts: check what's listening before changing settings
A local listening port is the entry point apps use to connect to the proxy on your computer; it's not the remote server port in a subscription. v2rayN commonly starts with local port 10808. Check Settings → Parameter Settings and the startup logs for the actual configuration. Investigate a port conflict first only if the logs report a bind failure, address already in use, or similar error.
Find out which process is using the port
On Windows, open PowerShell and find the process ID in the listening entries under OwningProcess. Then match the PID to a process in Task Manager's Details tab.
Get-NetTCPConnection -LocalPort 10808 -State Listen |
Select-Object LocalAddress, LocalPort, OwningProcess
On macOS, open Terminal and check the COMMAND and PID in the output. If your configured port isn't 10808, replace the number in the command with the port shown in the log error.
lsof -nP -iTCP:10808 -sTCP:LISTEN
- If another v2rayN instance is already running, exit it normally from its menu and try again. Seeing an Xray process doesn't necessarily mean there's a conflict: if it belongs to the current instance and the logs show no errors, it's expected to be listening.
- If another app you need is using the port, don't terminate an unfamiliar process. After confirming an alternative port is available, go to Settings → Parameter Settings and change the local listening port. This restarts the core, so reapply the system proxy afterward. Update the port in any apps where you entered the proxy address manually.
- If you're using v2rayN only on this computer, keep loopback listening enabled. Don't turn on Allow connections from the LAN just to resolve a conflict. Changing ports won't fix remote authentication errors or an expired subscription URL.
Common issues: identify the layer behind each symptom
The app flashes open and then disappears. What should I check?
First, check the architecture and extraction location again. If v2rayN still won't open on Windows, go to Event Viewer → Windows Logs → Application and look for an application error or .NET runtime entry from the time you launched it. Address the missing component named in the entry. On macOS, distinguish a system security warning from a damaged package or incompatible architecture. For the latter two, get a suitable package again rather than trying to fix the issue by raising permissions.
The subscription is saved, but why is the node list still empty?
Check which group is selected, make sure the URL has no extra spaces or line breaks, and manually update the current group. If the log shows 401 or 403, check with the subscription provider that the link is still valid. If it times out and you already have a working connection, try Update current subscription (through proxy). Without a working connection, switching this option back and forth won't make the local proxy connect by itself.
The node latency test succeeds, but why won't webpages load?
Make sure Automatically configure system proxy is enabled; selecting a node alone isn't enough. On Windows, check Settings → Network & Internet → Proxy. On macOS, go to System Settings → Network → your current network service → Details → Proxies. If your browser or an extension has its own proxy settings, cross-check with a browser that follows system settings. A successful latency test confirms only that one test request completed; it doesn't guarantee that every connection a webpage needs will work.
Webpages stopped loading after I quit v2rayN. Why?
If you weren't using a corporate or manually configured proxy before, reopen v2rayN, go to System Proxy, select Clear system proxy, and then exit normally. If your computer relies on a workplace proxy or automatic configuration script, restore the original settings instead of clearing everything. In particular, after an abnormal exit, check that the system isn't still sending requests to a local port that's no longer listening.
Keep a working fallback after initial setup
Test the full enable-and-disable workflow before setting up startup options or more complex routing. Exit normally and reopen the app to confirm your groups are still there. When you need the proxy, check the browser and logs; when you don't, make sure your computer returns to its previous network settings. This gives you a known-good setup to compare against if an upgrade or a different package causes problems.
- Note the client version, package architecture, and actual local listening port. When asking for help, include the exact error message and when it occurred; that's much more useful than simply saying it won't connect.
- Before sharing a screenshot or copying logs, hide the full subscription URL, access tokens, and node credentials. A subscription URL usually contains more than an ordinary webpage address.
- Once testing is stable, enable startup options or custom routing one change at a time. If something breaks, undo the last change instead of switching the core, node, and port all at once.