v2rayN First-Time Setup: Windows and macOS Installation Guide

A step-by-step guide to launching v2rayN, setting up core files, configuring local ports and system proxy, and importing your first subscription—with fixes for missing runtimes and port conflicts.

At a glance

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

Recommended

If 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

  1. 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.

  2. 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.

  3. 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.

  4. 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.

127.0.0.1
Loopback address on this computer
10808
Example local listening port
10818
Alternative ports to try if there’s a conflict

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.

Client downloadsChoose v2rayN / v2rayNG for your platform