For anyone setting up v2rayN on Windows or macOS for the first time. Choose a package for your operating system and CPU architecture, import a subscription, start the core, then test the local proxy with a single app. This order helps distinguish startup failures from subscription import issues and apps that aren’t using the proxy.
Installation and first launch
Check your CPU architecture before downloading. On Windows, go to Settings → System → About and check System type to distinguish x64 from ARM64. On macOS, open Apple menu → About This Mac and check the chip or processor: choose ARM64 for Apple silicon and x64 for Intel. When package names are similar, check whether each is an installer or archive and whether it includes a core. Don’t rely on file size alone.
Launching on Windows and macOS
Windows
- For an installer, follow the setup wizard. For an archive, extract all files to a directory you can write to, then open
v2rayN.exe. Don’t launch the app from the archive preview. - If startup reports a missing .NET component, note the framework name, version, and architecture shown in the dialog. If it requires
Microsoft.WindowsDesktop.App, install the matching .NET Desktop Runtime; the base runtime alone won’t work.
macOS
- After opening the disk image, follow the package instructions to move the app to Applications. For an archive, extract it fully before moving the app. Don’t drag an executable out of the app bundle and run it on its own.
- If macOS blocks the app, first verify the installer’s source, architecture, and exact warning. Then check the related alert in System Settings → Privacy & Security. If you see a malware warning, stop; don’t disable system-wide security protections.
Reaching the main window only confirms that the interface launched. After importing a configuration, check the logs to verify that the selected core is running.
Choosing a core and checking its files
v2rayN manages subscriptions, servers, and local settings; the core handles the actual connection. A subscription provides connection settings but does not install a core. For your first setup, choose a package that explicitly includes the required core. If your package doesn’t include one, check whether the app’s Check for Updates menu offers a download or update option for that core.
Xray core
RecommendedIf your provider supplies a VLESS and REALITY configuration, use an Xray core that supports it. After importing, keep the transport and security settings provided by your service.
Best for: subscriptions that explicitly require Xray
V2Fly core
If your provider supplies a VMess configuration specifically for V2Fly, you can use this core if your version of the app supports it. Check the transport and TLS settings too; the VMess protocol name alone doesn’t guarantee compatibility.
Best for: configurations with documented V2Fly compatibility requirements
In versions that include this page, check Settings → Parameters Settings → Core Type to match the protocol with its core. If the logs say a core can’t be found, first check that all required files are present at the path shown, then verify the architecture. The desktop app launching successfully doesn’t mean a separately downloaded core is compatible. Don’t rename an executable built for another operating system or architecture and place it here.
Importing your first subscription and enabling a server
Add a group
Open Subscription Group → Subscription Group Settings and choose Add. Enter a name you’ll recognize, paste the subscription URL from your provider into Optional Address, save, then switch to that group. If you have a single share link rather than a subscription URL, use the import-from-clipboard option in the Servers menu.
Update the current group
From the Subscription Group menu, choose Update Current Subscription (Without Proxy) if your network can reach the URL directly. Wait for the update result in the logs, then confirm that the current group contains server entries. Saving a group only saves the URL; it doesn’t confirm that the URL works.
Set an active server
Select a server in the group, right-click, and choose Set as Active Server. Menu wording may vary slightly by version; check that the server is actually active. Selecting a row alone doesn’t switch the connection. After activating it, check the logs for configuration parsing or listener errors.
Test with one app
Configure an app that supports manual proxy settings to use the local address and port currently shown in v2rayN, then visit a website that normally loads for you. Don’t change routing rules or enable TUN yet. Testing one app at a time helps separate the local proxy connection from system-wide proxy behavior.
Subscription URLs may contain account tokens, so redact the full URL in troubleshooting screenshots. Logs may also include server addresses, so check them before sharing. If an update reports success but the group is empty, make sure you’re viewing the right group and haven’t filtered the server list. Then check whether your provider returned subscription data rather than a login page or expiration notice.
Local ports and system proxy
Check the local listener settings under Settings → Parameters Settings, and use the ports shown in the interface and logs. The numbers below illustrate how to enter a port; they aren’t defaults for every version. A mixed listener can accept both HTTP and SOCKS requests on the same port, so don’t assume a separate port exists for each protocol.
- Choose the right proxy type: If the app requires an HTTP proxy, enter a port that supports HTTP. If it requires SOCKS5, use a SOCKS-compatible port. Don’t enter the remote server’s port in an app’s local proxy settings.
- Enable the system proxy next: After the single-app test works, open v2rayN’s System Proxy menu and choose Set System Proxy. On Windows, check Settings → Network & Internet → Proxy. On macOS, check System Settings → Network → your current network service → Details → Proxies.
- Check which apps are affected: The system proxy only affects apps that read that setting. If one browser works but another app doesn’t, check whether the second app has its own proxy settings before changing your subscription or switching cores. Before quitting, choose Clear System Proxy. If your device had a proxy configured by your organization, restore the original settings.
Common first-time setup issues
Missing runtime error when I double-click the app
Note the required framework and architecture shown in the dialog, install the matching runtime, and restart the app. If no dialog appears, check that the archive was fully extracted and that you’re launching the GUI app. Don’t copy individual runtime libraries from another computer to fill in missing dependencies.
The logs say a port is already in use. How can I check?
If the reported port is 10808, run netstat -ano | findstr :10808 on Windows and check the process ID on the listening line. On macOS, run lsof -nP -iTCP:10808 -sTCP:LISTEN. Quit the process only if you confirm it’s an old instance you started. If you change the port, save the setting, restart the core, and update any port entered manually in your apps.
Subscription update timed out, and the list is still empty
Check whether your current network can reach the subscription service and whether the URL saved in the group is complete. If you don’t already have a working server, choosing Update via Proxy usually won’t solve a first-time import problem. Ask your provider for a subscription URL that’s reachable directly, or import a working server they provided separately before updating.
The server shows a latency, so why won’t webpages load?
A latency result only shows that a probe received a response; it doesn’t mean your browser is using the same route. Confirm that the right server is active, check that the core is listening, and verify the browser’s proxy type and port. If manual proxy settings work but the system proxy doesn’t, focus on the system settings and whether the app reads them.
After quitting, even regular webpages won’t load
Check the system proxy settings to see whether they still point to v2rayN’s local port. A leftover proxy address won’t respond after the core exits. Clear the settings added during this setup, or restore the address and port you noted beforehand, then try the same webpage again.