This guide is for Windows and macOS users running v2rayN for the first time. It covers package selection, folder extraction, runtime requirements, core checks, the interface language, local ports, subscription imports, and the system proxy, with fixes for common first-launch errors. By the end, you should know the status of the client, core, node, and system proxy separately.
Confirm the system architecture and file location first
Check the processor architecture in your system information before choosing a package. Windows users typically choose x64, while ARM-based devices should use arm64. macOS also requires choosing between x64 and arm64. The wrong architecture may prevent launch or cause extra resource usage under a compatibility layer.
On Windows, do not run the main program from the archive preview window. Extract all files to a fixed folder, such as Applications\v2rayN in your user directory. v2rayN’s configuration, database, and core files rely on relative paths; dragging out only the main executable can make core detection fail.
The folder must be writable by the current account. Do not keep the program in a temporary download folder or a system folder that requires administrator access to modify. On first exit, the client saves the interface language, local ports, subscription groups, and routing settings; a write failure can make the configuration revert to defaults after restart.
Which files to check after extraction
- Make sure the main program and all other folders remain at the same level; do not copy only the executable.
- Keep at least 300 MB of free disk space. Later core and routing-database updates will write additional files.
- Make sure the folder name contains no unusual control characters. Ordinary Chinese, English, numbers, and spaces are usually safe.
- If you are migrating from an older version, keep the old folder intact and do not overwrite it immediately. After the first successful launch, migrate the configuration as needed.
First-launch sequence on Windows and macOS
On Windows, double-click the v2rayN main program first. If the system reports a missing desktop runtime, note the major version and architecture shown, then install the matching .NET Desktop Runtime. An x64 program needs the x64 runtime; installing only another architecture usually will not fix the launch problem.
After launch, the program may appear only in the system tray. Check the taskbar notification area before assuming it failed to start. Double-click the tray icon to open the main window; use the context menu to switch the system proxy, routing mode, and active node.
- Extract the complete folder and confirm that the current account has read and write access.
- Launch the main program and wait 10–20 seconds for the client to initialize its configuration folder and logs.
- Open the main window and go to “Settings” → “Preferences” to check the language and local listening ports.
- Open the log panel and confirm that no red startup error is repeating continuously.
- Import a valid configuration, run a latency test, and only then enable the system proxy.
Opening v2rayN for the first time on macOS
On macOS, move the app to a fixed application folder before opening it from Finder. If macOS asks you to confirm its source on first launch, go to “System Settings” → “Privacy & Security,” check the blocked app name, and use the system-provided Open Anyway option. Do not repeatedly extract multiple copies because of a permission prompt; it becomes difficult to tell which copy actually launched.
If the system says the app does not have permission to run, first confirm that the download and extraction completed correctly. Re-extract the original archive with a graphical archive utility; this is usually safer than changing permissions across the entire folder. If the program opens but cannot save settings, check that the current account owns the app data folder.
Check the client, core, and node separately
v2rayN manages configuration and the system proxy, while the selected core handles the actual connection. An open main window only confirms that the client interface started; it does not confirm that the core is running or that a node can connect. Keep these three layers separate during troubleshooting.
Go to “Settings” → “Preferences” → “Core Settings” and confirm that the core matches the configuration type. Configurations such as VLESS and VMess can usually be handled by the Xray core. Then select a node and set it as the active server, checking the logs for a local listening address and outbound connection records.
| Layer | Expected behavior | Check first when it fails |
|---|---|---|
| Client interface | The main window or tray icon is usable, and settings can be saved | Runtime, folder write permissions, and duplicate processes |
| Proxy core | The logs show a local port beginning to listen without repeated exits | Core files, configuration syntax, and port conflicts |
| Remote node | The latency test returns a value, and connection logs show outbound activity | Address, port, protocol parameters, and network reachability |
| System proxy | Browser requests reach v2rayN’s local listening port | The system proxy switch, browser-specific proxy, and bypass rules |
Takeaway: confirm local listening before testing the remote connection
If the logs do not show a listening port at 127.0.0.1, changing browser or subscription parameters will not help. Fix core startup and port conflicts first, then check the node protocol and remote address.
Set the interface language, local ports, and startup behavior
Go to “Settings” → “Preferences” → “v2rayN Settings” and switch the language to Simplified Chinese. Some 7.x releases apply the language change fully only after restarting the interface. Exit the client normally, then launch it again; do not terminate the process directly.
Local ports are used by applications to connect to v2rayN. A common setup uses 10808 for SOCKS and 10809 for HTTP; use the values currently shown in “Preferences” as the authority. Ports can be changed, but two programs on the same device cannot listen on the same address and port at the same time.
If your browser uses the system proxy, you do not need to enter a separate SOCKS address. Only command-line tools, development tools, or apps that ignore the system proxy need 127.0.0.1 and the corresponding port entered manually. Be sure to distinguish between SOCKS and HTTP.
| Setting | Suggested initial value | When to change it |
|---|---|---|
| Listening address | 127.0.0.1 | Keep the local loopback address when used only on this device |
| SOCKS port | 10808 | Change it only when the logs clearly report that the port is occupied |
| HTTP port | 10809 | Change it when an external tool is already using the port |
| Launch at startup | Disable during initial troubleshooting | Enable after several consecutive successful launches |
| Automatically update subscriptions | Update manually at first | Enable after confirming the group address and update method are correct |
Import a subscription and run the first connection test
Go to “Subscription Groups” → “Subscription Group Settings,” create a group, and paste the subscription URL provided by the service. The group name is for local identification and can describe its purpose. Save it, return to the main window, and choose “Subscription Groups” → “Update All Subscriptions (Without Proxy).”
The first update should normally not depend on an unverified proxy node. If the current network cannot retrieve the subscription directly, choose an update through the proxy only when the list already contains a working configuration. After the update, check the node count and protocol types instead of relying only on the “Update successful” message.
- Select a node and use the context menu to set it as the active server.
- Run a latency test and confirm that the result is neither a timeout nor an empty value. A latency result only shows that the test path is reachable; it does not guarantee that every website will open.
- From the tray menu, choose “System Proxy” → “Automatically Configure System Proxy.”
- Keep the default routing mode for the basic test and avoid adding complex custom rules for now.
- Open a familiar page in your browser and watch the logs for the corresponding connection.
- After testing, decide whether to enable mainland-China bypass or other routing rules.
VMess and VLESS are node protocols, not system proxy modes. The system proxy sends application traffic to a local port, routing rules decide whether requests use the proxy or connect directly, and protocol parameters tell the core how to connect to the remote server. These three concepts cannot replace one another.
Takeaway: test one node with the default route first
Use one known-working node to complete the loop of subscription update, latency test, system proxy, and webpage access before adding custom DNS or split-routing rules. Changing several layers at once makes the logs difficult to match to a specific cause.
Common first-launch errors and fixes
For an error, find the first log entry that caused the core to exit rather than focusing only on the connection failures that follow. Logs often show a chain reaction: a missing runtime exits the main program, a port conflict exits the core, and the stopped core makes the browser report that the proxy server is not responding.
Error: You must install or update .NET to run this application.
Cause and fix: The required .NET Desktop Runtime is missing, or its architecture does not match the program. Install the requested major version with the x64 or arm64 architecture, then restart v2rayN.
Error: A fatal error occurred. The required library hostfxr.dll could not be found.
Cause and fix: Runtime files are missing, or only the main program was copied without the complete folder. Re-extract the full package. For a version that depends on the runtime, repair the matching .NET Desktop Runtime.
Error: failed to start listener: bind: address already in use
Cause and fix: Port 10808, 10809, or the configured listening port is already occupied by another process. Exit duplicate v2rayN instances, or change the port under “Settings” → “Preferences,” then restart the core.
Error: failed to find an available destination
Cause and fix: The remote address cannot be resolved, the node parameters are invalid, or the current network cannot reach the target. Check the server address and port, refresh the DNS state, and use the logs to confirm whether the same target continues to fail.
Notice: “v2rayN” cannot be opened because the developer cannot be verified
Cause and fix: macOS blocked the first launch. Confirm the app source and filename, then go to “System Settings” → “Privacy & Security,” use the displayed Open Anyway option, and follow the confirmation steps.
Symptom: settings revert after restarting
Cause and fix: The program folder or app data folder is not writable, or the process may have been force-quit. Move the program to a location writable by the current account, exit normally once, and then check the configuration file’s modification time.
What to keep in the logs
- Keep about 20 lines before and after the error so the first failed entry can be identified.
- Record the v2rayN major version, operating system version, and processor architecture.
- Record the current core type, local listening port, and time of the error.
- Before sharing logs, remove subscription URLs, node domains, user identifiers, and authentication details.
Frequently asked first-time setup questions
These issues often appear after the client has opened but before the connection chain is fully established. Follow the same order: local listener, active node, system proxy, then routing rules.
Why is it still running after I close the window?
v2rayN usually minimizes to the system tray and keeps working. To exit completely, right-click the tray icon and choose “Exit.” Closing only the main window does not stop the core or automatically revoke the current system proxy.
The subscription updated successfully. Why is the node list still empty?
Open “Subscription Groups” → “Subscription Group Settings,” confirm that you updated the current group, and check its filters. Run the update again, then see whether the number of configurations parsed in the logs is zero.
The latency test returns a value. Why can’t the browser open pages?
First check that the tray’s system proxy is set to “Automatically Configure System Proxy,” then make sure the browser has not overridden it with its own proxy. Check the logs while opening a page; no connection record usually means the traffic never reached the local port.
Port 10808 is occupied. Can I change it to another port?
Yes. Go to “Settings” → “Preferences” and change it to an unused port, such as 10818, then save and restart the core. Update command-line tools and other manually configured proxy apps to use the new port as well.
Do I have to select a node again after every startup?
When it exits normally, v2rayN saves the active server. If it returns to the default every time, check the configuration folder’s write permissions first. After confirming that saves work, enable launch at startup in Preferences.
Post-setup acceptance checklist
Run a complete acceptance check before considering the first installation finished. An open main window alone is not enough. The client should save settings, the core should listen steadily on a local port, the active node should produce valid outbound records, and the system proxy should be possible to enable and disable.
- After restarting v2rayN, the interface language, subscription groups, and local ports retain their previous values.
- The logs show core startup and local listening records without a repeated exit loop.
- The active node’s protocol, address, and port match the information provided by the service.
- With the system proxy enabled, browser requests appear in the logs; after disabling it, the system proxy settings are restored.
- Port 10808, 10809, or a custom port is not taken over by a second client instance.
- The Windows runtime matches the program architecture, and the macOS first-launch permission has been confirmed.
- When updating subscriptions, you can explicitly choose whether to use the proxy instead of relying on an unknown state.
- Leave complex routing, DNS, and launch-at-startup settings disabled for now; add them one at a time after the basic connection is stable.