v2rayN Installation and Setup Guide for Windows and macOS

At a glance

Start with four essentials: download the package for your OS and processor, make sure the core starts, import a working subscription, and test the connection with an explicit proxy request. Windows and macOS differ mainly in how the app launches, runtime requirements, and system permissions. This guide follows the setup process for users who have extracted v2rayN but can’t get online yet. Configure routing and startup after confirming the connection works.

1. Choose the right download: OS, architecture, and runtime

v2rayN is a desktop client interface; connections are handled by the core it launches. Seeing the main window doesn’t mean the core is running properly. When downloading, check the platform, processor architecture, and whether the package includes the required runtime and core—not just whether the filename contains v2rayN.

Complete package for your device

Recommended

For a first install, choose a complete package that the download page says includes the required components. Windows packages come with either the classic WPF interface or the cross-platform interface. On macOS, choose the package for that platform; Windows executables won’t run there.

Best for: first-time installs and anyone who wants to avoid adding components manually.

Packages that require a separate runtime

Choose one only if you know which dependencies are missing. If startup reports that .NET is missing, install the runtime specified for that package. The Windows WPF interface typically requires the matching .NET Desktop Runtime, not just the standard runtime.

Best for: users who already have the runtime set up and can interpret startup errors.

On Windows, check Settings → System → About for the system type. On macOS, check the chip under Apple menu → About This Mac. Intel devices typically use x64; Apple silicon devices should use arm64. Don’t guess based on your browser, and don’t make emulation your default choice for a first install.

2. Extract and launch: choose a permanent folder

Extract the entire Windows portable package to a stable folder you can write to, such as C:\Tools\v2rayN. Don’t launch the main program from inside an archive, and don’t extract just the executable: keep the core, resources, and configuration folders in their relative locations. You don’t need administrator privileges for normal use; grant permission when prompted for TUN or other system-level operations.

Getting ready to launch on either system

Windows

Extract the complete package, then run the included main program. Avoid temporary extraction folders.
If prompted to install a runtime, note its name and architecture before adding the dependency.
If startup fails, check your security software’s logs to see whether it blocked the core. Don’t disable all protection.

macOS

Move app bundles to Applications. Fully extract other archive packages according to their instructions.
If macOS blocks the app on first launch, verify its source, then check the prompt under System Settings → Privacy & Security.
Use the system’s approval option only after confirming the app is trustworthy. Don’t disable security checks system-wide.

Get the app launching from a permanent location before importing subscriptions or adding a login item. Moving it later can break shortcuts.

If macOS reports that the app is damaged, incompatible with your architecture, or unable to run, don’t assume every error is a permissions issue. Check the package type and confirm it was fully extracted, then read the system prompt. Before moving the app or upgrading, export a configuration backup using the client’s built-in feature. Backups contain subscription credentials, so don’t upload them to public locations.

3. Configure the core and subscription in order

Start with a core supported by the package and its default settings. Leave TUN, complex routing, and multiple upstream proxies off for now. VMess and VLESS are protocols; Xray is a core; v2rayN is the management interface. They’re different parts of the setup. The selected core must also support any transport or security options used by your nodes.

Check the core

Go to Settings → Parameter Settings and look for the available Core type options. Some interfaces list these separately under Core type settings. Keep the package’s default configuration for your first setup, confirm the core file exists, and check the logs for errors such as “file not found” or startup failure.
Note the ports

In Settings → Parameter Settings, check the local listening port and address, and note their actual values. Keep the listener bound to loopback for your first setup. Leave “Allow connections from the LAN” off to avoid exposing your local proxy to other devices.
Add a group

Go to Subscription groups → Subscription group settings and select Add or + to create a group. Enter a label that identifies the source, then paste the full subscription URL, such as https://example.com/sub?token=xxxx. This example won’t connect you to a server.
Update the subscription

After saving, go to the Subscription groups menu and select Update all subscriptions (without proxy). If you don’t have a working connection yet, try using your current network first. Only try updating through a proxy if direct access fails and you already have a working proxy; otherwise, you may create a circular dependency.
Select a server

Choose an entry from the updated list and use the right-click menu to select Set as active server, or use the equivalent option in your interface. Check the logs to confirm the core started successfully, then test the connection. A successful subscription update only means the list was retrieved—not that every server is reachable.

Get node settings from a valid subscription or your service provider. Don’t guess the VLESS public key, server name, or transport path. If the list is empty, check the subscription’s validity period, group filters, and update logs first. Adding the same URL again usually creates duplicates and won’t fix access problems.

4. Test the local port and system proxy separately

The system proxy directs apps that honor its settings to a local listening port; it doesn’t automatically route all traffic through the proxy. Terminals, some browser extensions, and apps with their own network stack may use separate settings. Test the local endpoint first, then enable the system proxy. This makes problems easier to pinpoint than changing several settings at once.

127.0.0.1

A local loopback address, not a remote server address

10808

Example SOCKS port used in the commands below

15 seconds

Maximum wait time for the requests below

10808 is just an example port; it may not be the default for your version. First confirm that the port accepts SOCKS or a compatible mixed connection. In Windows PowerShell, use curl.exe to avoid command alias differences. In macOS Terminal, use curl. Run the command for your operating system only; you don’t need to run both.

# Windows PowerShell
curl.exe --proxy socks5h://127.0.0.1:10808 --connect-timeout 5 --max-time 15 -I https://example.com/

# macOS Terminal
curl --proxy socks5h://127.0.0.1:10808 --connect-timeout 5 --max-time 15 -I https://example.com/

socks5h sends domain name resolution through the proxy. A normal HTTP response means this explicit proxy request worked; it doesn’t mean every website or app is using the proxy. If the local port can’t be reached, check that the core is running and the port matches. If the local connection succeeds but the remote handshake times out, check the server and transport settings.

Enable the system proxy: In v2rayN, open System proxy → Set system proxy automatically from the main window or tray menu. The menu location varies by interface.
Check Windows: Go to Settings → Network & internet → Proxy. Confirm the manual proxy points to your local machine and uses the client’s HTTP or mixed port.
Check macOS: Go to System Settings → Network → your current network service → Details → Proxies. If you use Wi-Fi and Ethernet, check the service that’s currently connected.
Test in a browser: Temporarily disable extensions that override proxy settings, then test the same site. To check your exit IP, compare it before and after enabling the proxy and confirm the result with your service provider.

5. Configure routing, TUN, and startup after connecting

The system proxy controls which apps send traffic to the local proxy; routing rules determine which exit the core uses for traffic it receives. These are separate layers. With rules that bypass mainland China, traffic to websites in mainland China may still go direct. That’s expected and doesn’t mean the proxy is broken just because one site in mainland China shows a direct connection.

Setting	Recommended for first-time setup	When to change it
Routing rules	Start with a preset included in the package and note the current mode.	Add domain and IP rules only after confirming the basic connection works.
TUN	Leave off initially to reduce permission and routing variables.	Consider enabling it only if you need to route apps that ignore the system proxy.
LAN access	Keep off and listen on this device only.	Enable only if other devices need access, and configure access controls first.
Launch at startup	Test starting and quitting manually first.	Enable it after the app location and proxy behavior are stable.

TUN involves a virtual network interface, routing, and DNS; it isn’t simply a “faster system proxy.” Follow the permission requirements for your platform and package. If your network stops working after enabling it, turn TUN off and restore the previous proxy settings. Don’t change DNS, routes, and subscriptions at the same time. Change one setting at a time to identify the cause.

Check startup settings in this order

On Windows, look for Launch at startup under Settings → Parameter Settings. If it isn’t available, use the startup app option provided by Windows. Don’t create multiple startup entries.
On macOS, check apps that open at login under System Settings → General → Login Items & Extensions. Depending on your macOS version, this may be listed as Login Items.
Check whether the system proxy turns on automatically at startup and whether it’s cleared when you quit. Restart and log in once to confirm the core starts correctly, then check your browser.
Before quitting normally, select System proxy → Clear system proxy, then exit the client. If the app crashes and you lose internet access, first check whether your system still points to a local port that is no longer running.

6. Common first-install questions

The window opens, but why does the core still fail to start?

Start with the first startup error in the logs. The interface and core are separate processes. Common causes include an incomplete extraction, a quarantined executable, or a port already in use. Close any other v2rayN instance, then extract the package again. An open window doesn’t mean the proxy is running.

Windows says the local port is in use. How do I find out what’s using it?

Run the port-check command below in a terminal. Check the process ID in the last column, then find the program name in Task Manager. If you need to change the port, update the system proxy and any apps you configured manually. Don’t terminate an unfamiliar system process.

The subscription updated successfully, but why won’t my browser load websites?

First, confirm that you’ve selected an active server, then run an explicit proxy request. If that works but your browser doesn’t, check the system proxy, browser extensions, and any separate proxy settings. If the explicit request also fails, check the core logs. Repeatedly toggling launch-at-startup settings won’t help.

After quitting the client, even regular websites won’t load. Why?

Reopen the client and select System proxy → Clear system proxy. If the app won’t start, open your system network settings and disable the manual proxy that points to the local port. If your network is managed by your organization, check its existing settings before making changes.

# Windows: replace the port with the actual listening port
netstat -ano | findstr :10808

# macOS: find the process listening on this TCP port
lsof -nP -iTCP:10808 -sTCP:LISTEN

When troubleshooting, keep the time the error occurred, system architecture, package type, and error details from the logs. Before sharing screenshots or logs, redact subscription URLs, access credentials, user identifiers, and sensitive server settings. Once the basic connection is stable, add routing rules and automation one at a time as needed. This helps prevent a small, reproducible problem from turning into several interacting configuration issues.