For anyone setting up v2rayN on Windows or macOS for the first time. Choose the download for your OS and processor, prepare the runtime, import a subscription, and select an active server. Then check the local listener, system proxy, and routing. Start with the system proxy and leave TUN off. If something goes wrong, troubleshoot in this order: app startup, core startup, proxy connection, then traffic routing.
Choose a download: Desktop Edition, WPF, and processor architecture
v2rayN is a desktop client for managing server configurations, running proxy cores, and providing system proxy controls. It does not include servers. Before you begin, get a valid subscription URL or server share link. Opening the main window alone does not establish a working connection.
On Windows, go to Settings → System → About and check System type. On macOS, open the Apple menu → About This Mac and check Chip or Processor. Choose ARM64 for Apple silicon and x64 for Intel. For Windows on ARM, check the release notes too; the file extension alone does not tell you whether a package will run.
Desktop Edition
RecommendedUses a cross-platform interface. Download the package for Windows or macOS. The setup is similar on both platforms, but system permissions and proxy settings differ. This guide focuses on this edition.
Best for: first-time users and anyone who wants a consistent workflow across both desktop platforms.
Windows WPF Edition
Keeps the classic Windows interface and runs on Windows only. It is not a macOS installer. Differences in interface framework do not mean differences in server protocols; configuration support depends on the core in use.
Best for: users familiar with the classic Windows interface who want to keep using it.
Check the current instructions on the download page. Installers, archives, and disk images require different steps, so not every release can simply be extracted and run. On first use, don't launch both interface editions at the same time; they may compete for local ports.
First launch on Windows: app folder and runtime
An archive may contain the app, core directories, and other required files. Moving only the main executable to your desktop can leave the window working while the core fails to start. If you downloaded an archive, extract all its contents to a fixed location you can write to, such as C:\Users\Public\Tools\v2rayN, and make sure the folder permissions suit your needs.
-
Extract the package
For an archive, select Extract All in File Explorer, then open the extracted folder. For an installer, follow the setup wizard. Don't run the app from an archive preview window.
-
Install the required runtime
If startup reports a missing .NET runtime, note the required runtime type, major version, and architecture, then install it from Microsoft. The WPF edition needs the matching .NET Desktop Runtime. Installing only the SDK or a runtime for another architecture may not fix the issue.
-
Launch as a standard user
Open the main app with standard user permissions and test the basic proxy setup first. Don't treat Run as administrator as a universal fix. Handle extra permissions for features such as TUN only after the basic connection works.
-
Check write permissions
Open Settings, save once, then quit normally and relaunch. If the language or other options revert, check whether the configuration folder is writable and make sure you haven't launched a different copy of the app.
First launch on macOS: app location and security prompts
For a .dmg download, open the disk image and drag the app to Applications as instructed. For an archive, extract it and move the app to a permanent location. After installation, eject the disk image and launch the app from Applications instead of running a temporary copy from the image.
- Architecture mismatch: Check the chip listed in About This Mac and download the ARM64 or x64 package that matches. Don't change macOS security settings as your first response to a startup failure.
- Developer cannot be verified: Check where the file came from first. If macOS offers Open Anyway under System Settings → Privacy & Security, use it only after verifying the source and follow the prompts. The location of this option may differ between macOS versions.
- App is damaged: Don't assume this is just a permissions issue. Download the complete release package for the right architecture, then check its release notes and system requirements. Don't bulk-remove security attributes from other apps.
- Permission required to change proxy settings: Confirm the system prompt only when you intentionally change the system proxy. Launching the app successfully does not mean the system proxy was set; check the active network service separately.
macOS system proxy settings are configured per network service. After switching between Wi-Fi and Ethernet, go to System Settings → Network → the active service → Details → Proxies to check the current settings. On older macOS versions, look under System Preferences → Network → Advanced.
First-time setup: language, subscription, and active server
The interface language does not affect server protocols. To change it, look for the language option under Settings → Preferences, save, and restart if prompted. Some releases place the language option elsewhere in Settings. This guide uses Chinese menu names; look for the equivalent options in your interface.
-
Add a subscription group
Open Subscription Group → Subscription Group Settings, add a group, and enter a name and subscription URL. Remove any spaces at the beginning or end of the URL, and make sure you copied a subscription link rather than a website login URL.
-
Update the subscription
Return to Subscription Group and run the relevant update action. If you don't have a working proxy yet, try updating without one first. Only try updating through a proxy if you already have a working connection and a direct update fails.
-
Check the import
Make sure servers appear in the list and have protocol, address, and port values. If you get a webpage or login prompt instead, stop retrying the import and ask the provider to confirm the subscription URL and access requirements.
-
Set the active server
Right-click the server you want and select Set as Active Server. Then check the core logs to confirm it starts normally. Selecting a row in the list may not switch the server actually in use.
If you have a single vmess:// or vless:// link, copy it in full and use the Import from Clipboard option under Server. A share link and a subscription URL are different: a share link usually imports one server, while a subscription URL fetches and updates configurations in a group.
System proxy and routing: configure them separately
The system proxy lets apps that follow system proxy settings connect to the local listener. Routing rules determine whether traffic that reaches the core goes through the proxy, connects directly, or is blocked. These settings are not interchangeable. For your first test, use the system proxy and leave TUN off to avoid extra variables such as permissions, virtual adapters, and DNS interception.
10808 is an example port for reference, not a guaranteed default for every version. First check the actual local listener type and port under Settings → Preferences, then match your system settings. If the interface provides separate HTTP and SOCKS ports, enter each under the correct protocol; don't copy settings for a combined listener.
Check the local listener
- Listen address
127.0.0.1(example for local access)- Listener type
- HTTP/SOCKS combined; check the current settings
- Example port
10808- LAN access
- Leave off during initial setup
Confirm the core is listening on this port before configuring apps to use it. Don't expose the listener on every network interface just to troubleshoot.
Check proxy connections
- System proxy
- Select Set system proxy automatically
- HTTP address
127.0.0.1- HTTP port
- Match the actual HTTP or combined listener
- TUN mode
- Keep off during initial testing
The system proxy does not route all device traffic. Apps that connect directly or use their own proxy settings may ignore it.
On Windows, check the result under Settings → Network & internet → Proxy. On macOS, check the proxy options for the active network service. For the first test, don't enable a manual proxy, an automatic configuration script, and another proxy app at the same time; otherwise, it can be hard to tell which settings are taking effect.
- Everyday routing: Choose a routing rule in v2rayN that suits your needs, then check the specific rules under Settings → Routing Settings. A mode name doesn't tell you what the rules actually do.
- Temporary test: If you suspect a rule is sending a destination direct, briefly switch to a rule that proxies traffic once it reaches the core, then test the same destination. Restore your everyday routing rule afterward.
- Routing limits: Global proxy routing handles only traffic that has already reached the core. It does not make every app follow the system proxy automatically.
- DNS settings: Keep the current configuration if it's working. Investigate DNS settings for the core in use only when logs indicate a resolution failure or an unexpected DNS path. Avoid changing multiple variables at once.
Test the connection: an open port doesn't guarantee a working website
Test from the client outward. First confirm that the app and core are running, then check the local port, and finally test a proxy request. The commands below assume you have confirmed that the HTTP or combined port is 10808. If yours differs, replace the number first. The destination in the commands is just an example.
Windows: check the listener, then send a request
Test-NetConnection -ComputerName 127.0.0.1 -Port 10808
curl.exe --proxy http://127.0.0.1:10808 --connect-timeout 10 --max-time 20 -I https://example.com/macOS: specify the proxy explicitly
curl --proxy http://127.0.0.1:10808 --connect-timeout 10 --max-time 20 -I https://example.com/Specifying a proxy explicitly avoids differences in whether a terminal reads system proxy settings, but core routing rules still apply. A successful Windows port test means only that a local process accepted the connection. An HTTP response means only that the destination was reachable under the current rules; it doesn't prove that every website or app will work.
| What you see | Check first | Next step |
|---|---|---|
| Local connection refused | Is the core running, and does the port match? | Check the core logs for startup failures or port conflicts |
| Local connection succeeds, but request times out | Active server, remote connection, and routing | Check the logs for the same request, not just older errors |
| Command works, browser doesn't | Is the browser using the system proxy? | Check the browser's own proxy settings and reconnect |
| Some domains fail | Routing rules, DNS, and destination service status | Retest the same destination, changing only one setting at a time |
Common first-use questions
The window opens, so why can't I access the internet?
Check in order that a server was imported, set as active, and started successfully in the core. Then confirm that System Proxy is set to Set system proxy automatically. If an explicit proxy command works but the browser doesn't, check how the browser connects before changing server protocols.
A port is in use. Should I change all the ports?
First quit any other v2rayN instance or core process that's still running. On Windows, run netstat -ano | findstr :10808 to check listening ports, then look up the matching PID in Task Manager. Don't stop system processes you don't recognize. If you do change the port, update the settings in every app that uses the proxy.
What if the first subscription update times out?
Check that the URL is complete, the subscription is still valid, and the system date and time are correct. If you don't have a working proxy, don't keep retrying with Update through proxy. Try that option only if you have a working server and a direct update fails. For more help, see subscription update troubleshooting.
Can't access websites after quitting the client?
Reopen the client, select Clear system proxy under System Proxy, then quit normally. If the app stopped unexpectedly, clear the local address it left behind on the system proxy settings page. Make a note of any proxy or script required by your workplace network before changing or removing it.
Should I turn on TUN right away?
No. First verify the basic connection with a browser and an explicit proxy command. Configure TUN separately only if an app ignores the system proxy and you need to route its traffic. Check permissions, routing, and DNS, then retest requests that worked before. TUN is not a required fix for a failed connection.
After the initial setup
A successful setup isn't just a changed icon. Confirm that the active server is clear, the core starts without errors, requests follow the expected route, and your normal network connection works again after you quit. Keep this minimal working setup, then add startup options, extra rules, or TUN one at a time so you can roll back changes if needed.
- Note the app folder, interface edition, and actual listening port so you don't accidentally launch an older copy later.
- Back up essential configuration using the client's backup options. Store backups containing subscription URLs or credentials somewhere secure.
- Quit the app and core normally before upgrading. Don't overwrite files while they're running.
- To configure traffic routing, read the routing guide. For connection issues, use the logs and request behavior to find the right troubleshooting steps.