v2rayN First-Time Setup Guide: Windows and macOS Installation, Settings, and Common Issues

1. Confirm your system architecture and runtime before downloading

v2rayN is a desktop GUI client for managing subscriptions, nodes, routing rules, and the system proxy. Actual protocol connections are handled by core processes such as Xray or v2fly. On a first install, a working client window does not prove that the core is running; check the main program, core files, and local listening ports together.

Check your device architecture before downloading. In Windows, open Settings → System → About and find System type to confirm x64 or ARM64. In macOS, open About This Mac from the Apple menu and check whether the device uses Apple silicon or an Intel processor. Choosing the wrong build can prevent the app from launching, make the core exit immediately, or trigger an incompatibility warning.

1. Confirm the architecture

   Check System type in Windows and processor information in macOS; do not mix x64 and ARM64 packages.

2. Get the client

   Open this site's download center and choose the v2rayN 7.x build for your desktop operating system. Do not substitute an Android package for the desktop client.

3. Extract the archive completely

   Extract the entire archive to its own directory. On Windows, a folder under your user profile is a good choice; avoid locations that require elevated permissions for routine writes.

4. Check the runtime

   If you chose a build that depends on a runtime, install the matching .NET 8 Desktop Runtime when prompted. Self-contained builds normally need no separate runtime.

5. Launch it for the first time

   On Windows, run the main program. On macOS, move the app to Applications, launch it, and confirm permission to open it if macOS prompts you.

6. Keep the original folder structure

   Do not move individual executable files after launch. The core, configuration, logs, and main program should remain in the complete directory structure.

If Windows reports a missing runtime, first determine whether you downloaded a runtime-dependent or self-contained build. Repeatedly running as administrator will not install missing components. If macOS blocks the first launch, open System Settings → Privacy & Security, verify the blocked app's name, and use the system's Open Anyway option; do not bypass source verification by removing security attributes.

2. Choose the core first, then adjust the basic settings

After opening the main interface, go to Settings → Parameter Settings → Core type. If your subscription includes VLESS, Reality, XTLS Vision, or similar configurations, choose the Xray core first. For traditional VMess configurations only, the v2fly core can handle basic connections. The core must be compatible with the node protocol and transport settings; otherwise, a node may import successfully but fail at startup with an unsupported-field error or exit immediately.

You do not need to change every basic setting at once. Keep the default log level initially, confirm the local SOCKS and HTTP ports, and only then decide whether to enable startup. Common examples use 10808 for SOCKS and 10809 for HTTP, but always follow the local listening settings shown under Settings → Parameter Settings.

• Core type: Choose Xray for normal new configurations; switch only when you specifically need compatibility with an existing v2fly configuration.
• Local address: Keep 127.0.0.1 when the proxy is for this computer only. Do not switch to listening on all interfaces just to troubleshoot.
• SOCKS port: The example is 10808; enter it separately in apps that support SOCKS5.
• HTTP port: The example is 10809; browsers, command-line tools, and the system proxy can use it.
• Log level: Keep info during the initial setup. Temporarily switch to debug when diagnosing a failure, then switch back to prevent logs from growing rapidly.

3. Import the subscription and check the node fields

With the complete subscription URL ready, open Subscription groups → Subscription group settings → Add in the main interface. Enter a group name, paste the URL, save it, and choose Update all subscriptions. Button locations may vary slightly between 7.x releases, but the order remains the same: create a subscription group first, then update it. Do not import a subscription URL as if it were a single node link.

A successful update is not confirmed merely by a “Completed” message. The main list should contain nodes with valid values for the protocol, address, port, and transport columns. If the list is empty, check for spaces at either end of the URL, truncation by a chat app, or a subscription service that requires an existing proxy for updates.

After importing the nodes, select one and set it as the active server, then watch the status bar and core logs. A connection usually passes through three stages: generating the configuration, starting the core, and listening on the local port. If the log stops before configuration generation, check the node fields first. If it says the address is already in use, there is a local port conflict. If the core is listening normally but the connection times out, check node availability, the network path, and the system proxy.

4. Configure the system proxy and startup separately

Once the v2rayN core is running, your computer has a usable proxy port, but that does not automatically route every app through it. To proxy browsers and apps that follow system network settings, choose “Set system proxy automatically” from the v2rayN tray menu or system proxy feature. Before exiting the client, restore the system proxy so it does not continue pointing to the stopped 127.0.0.1:10809 listener.

Windows Run as administrator and automatic startup are not the same thing. A normal local proxy usually does not require elevation every time; Windows prompts only when firewall rules, protected-folder writes, or specific system settings need authorization. Keeping the program in a protected folder can repeatedly cause permission problems when saving settings or updating, so a fixed directory writable by the current user is preferable.

After enabling login launch on macOS, open the Login Items page in System Settings and confirm that v2rayN is allowed to run in the background. If the app is running after login but the proxy is not working, check the core, the retained active node, and the system proxy separately; do not judge the connection solely by the menu bar icon.

5. Complete the first verification with ports, commands, and logs

After the initial setup, run two rounds of tests. First, bypass the system proxy and send a request directly through v2rayN's HTTP port to verify the core and node. Then enable the system proxy and open a site in a browser to confirm that system settings point to the local port. This separates node failures, port conflicts, and system proxy errors.

Check port 10809 on Windows:
netstat -ano | findstr 10809

Check port 10809 on macOS:
lsof -nP -iTCP:10809 -sTCP:LISTEN

Test through the local HTTP proxy:
curl --proxy http://127.0.0.1:10809 https://v2raymap.com/

If the port command produces no output, the core is not listening on that port. Return to v2rayN and check the core log and local port settings. If the port is listening but curl reports a refused connection, verify that you entered the HTTP port rather than the SOCKS port. For a SOCKS5 test, change the parameter to the appropriate SOCKS5 proxy format and use the actual port.

Start log troubleshooting with the first clear error, not just the final line. Port conflicts often include “address already in use”; incompatible node fields identify the specific configuration item; DNS or remote connection failures commonly show timeout or connection refused. Note when the error occurred and compare it with the action you just took; this is faster than switching nodes repeatedly.

6. The most common Windows and macOS installation pitfalls

Across both platforms, the main problems are incomplete directories, mismatched architectures, missing runtimes, and inconsistent port settings. Windows is also affected by protected-folder writes, firewall authorization, and leftover processes; macOS more often involves first-launch permission, unapproved login items, and a system proxy that was not restored after quitting.

After installation, keep a reproducible baseline: use the Xray core, set the local address to 127.0.0.1, record the actual SOCKS and HTTP ports, verify at least one node with a command-line test, and confirm that the system proxy can be enabled and restored manually. Add routing rules, LAN sharing, or more complex policies only after this baseline is stable.

• Back up subscription groups, routing rules, and custom settings before updating the client.
• After changing ports, update the system proxy and every app where a proxy was entered manually.
• When a node is unavailable, try another node from the same subscription before reinstalling the client.
• A failed subscription update and a failed node connection are separate paths; investigate their errors separately.
• Restore the system proxy before quitting to avoid leaving network settings pointed at an empty local port.