Set up v2rayN in this order: confirm your operating system and architecture, install the app completely, check its runtime requirements, import nodes, then test the local proxy. This guide covers Windows and macOS desktops and distinguishes app launch failures, core startup errors, and browsers that bypass the proxy. It also explains which menus, ports, and logs to check when connecting for the first time.
Choose the Right Download: Check Your OS, Architecture, and App Build
v2rayN is a desktop client. Its interface manages nodes, generates configuration, and launches a proxy core. An open window does not mean the core is running, and a visible node does not mean browser traffic is using the proxy. Check these three layers separately during setup instead of repeatedly reinstalling the app when a webpage fails to load.
Choose a package by operating system and processor architecture in the download center. The classic WPF interface for Windows and the cross-platform desktop interface are different builds; macOS cannot run Windows executables. Read the requirements for the specific package before downloading. File size alone does not tell you whether it includes a runtime or core.
| What to Check | Windows | macOS |
|---|---|---|
| System architecture | Go to Settings → System → About and check System type. | Open the Apple menu → About This Mac and check Chip or Processor. |
| Architecture match | x64 is for common 64-bit Intel and AMD processors; ARM64 is for Windows on ARM. | Choose ARM64 for Apple silicon and x64 for Intel processors. |
| App format | Check the download page for the installer or archive, and identify the interface type. | Extract or mount the package as instructed, then install the app. |
| Runtime requirements | Check whether the package is self-contained or requires a separate runtime. | Check the minimum OS version, architecture, and whether the package is self-contained. |
The menu names below use the Chinese labels found in common desktop builds. Settings may appear on different tabs depending on the release. If a label differs, look for fields such as subscription groups, system proxy, or Core type rather than relying on the location shown in an older screenshot.
Install the App: Extract on Windows and Open for the First Time on macOS
Installation approach: place the app in a fixed location before configuring it
Windows
- Extract the entire archive first, for example to
D:\Tools\v2rayN. Do not run the app from the archive preview window. - Keep the package’s subfolders and dependency files. Do not copy only the main executable to your desktop.
- Use a directory your account can write to, so routine configuration changes are not blocked by permissions.
- If you choose an installer, follow its installation steps instead of applying the archive instructions to the installed version.
macOS
- For a disk image, follow the instructions to copy the app to Applications, then launch it from there.
- Extract archives first and preserve the app bundle structure. Do not modify files inside the bundle.
- Do not keep running the app from a temporary extraction in Downloads or from a mounted disk image.
- If macOS blocks the app on first launch, distinguish a developer verification prompt from a clear security warning.
Choose a permanent location before importing subscriptions or enabling launch at login. This helps avoid broken shortcuts and changes to the app’s launch path.
A short path on Windows makes troubleshooting easier; Chinese characters in a path do not automatically prevent the app from running. Check whether the directory is writable, the files are complete, and security software has quarantined a dependency or core file. If you find a quarantine entry, verify the file’s source and the specific warning before taking action. Do not disable system protection across the board.
Runtimes and Startup Logs: Diagnose App and Core Errors Separately
Some Windows builds require a compatible .NET runtime; others are self-contained. If a runtime is missing, use the framework name, major version, and architecture shown in the startup dialog. WPF builds typically require the matching Desktop Runtime. Installing only the SDK or a runtime for another architecture may not meet the app’s requirements. This guide does not specify a fixed runtime version because requirements vary by release.
- The main window never appears: Note the full system error and check the architecture, runtime, and minimum OS requirements first.
- The main window opens, but reports a missing core: Check that the archive was fully extracted, that the package includes the selected core, and that security software has not quarantined its files.
- The core exits immediately after launch: Check the first startup error in the client log. Pay particular attention to port conflicts, configuration fields, and protocol support.
- macOS reports an architecture mismatch: Recheck whether you have an Apple silicon or Intel build. Do not treat an architecture issue as a subscription error.
You generally do not need administrator privileges for ordinary system proxy use. Features such as TUN and route changes may require extra permissions, but they are not needed for an initial test. Start with a basic proxy test under a regular account to avoid complications from permission changes and traffic-routing features.
Initial Setup: Language, Core, and Subscription Import
Leave network-related settings at their defaults and change only what you need. The interface language affects menu labels, not server protocols. A subscription URL retrieves a node list; it does not configure the local listener or system proxy. Subscription links may contain access credentials, so hide the full URL in screenshots and support logs.
-
Set the interface language
Open Settings, find the language option, and select Simplified Chinese. Some builds place this under Settings → Parameter Settings. If prompted to restart, quit the client normally and reopen it before continuing.
-
Check the core
Go to Settings → Parameter Settings → Core type and check which core is selected for the protocols you use. This option may be on a separate tab. Confirm that the package includes the required core before saving, and avoid changing several networking options at once.
-
Create a subscription group
Open Subscription Group → Subscription Group Settings, add a group, and enter a subscription URL you already have. The group name is for local reference only. Do not add spaces, explanatory text, or line breaks to the URL field.
-
Update the node list
From the Subscription Group menu, choose the option to update all subscriptions. If you do not yet have a working proxy, update without using a proxy. Once the update succeeds, check whether the node count changed, then select a node as the active server.
-
Enable the system proxy
After confirming that the core log shows no startup errors, select Set system proxy automatically from the client’s System Proxy menu. Test a webpage in your browser, then adjust routing rules or the subscription update interval if needed.
If you have a single node share link rather than a subscription, use the corresponding import option in the Server menu. Do not paste it into the subscription URL field. Updating a subscription connects to a subscription server; importing a node parses its connection parameters. Each has different troubleshooting steps.
Choose a Core by Protocol Support, Not by Its Name or Speed
v2rayN is a client; Xray and V2Fly are proxy core projects. Their protocol and transport support is not identical. Whether a node works depends on its settings and the selected core’s capabilities. Switching cores does not guarantee better speed, and cannot fix an expired server address or incorrect credentials.
Xray core
RecommendedFor a first setup, check whether Xray supports the nodes you already have. Nodes using VLESS and REALITY require a core that supports the specific combination. Preserve all transport and security settings supplied by your provider.
Best for: subscriptions that explicitly require Xray or include supported protocol combinations.
V2Fly core
When using V2Fly, check each node’s protocol and transport against the core’s supported features. Shared protocols such as VMess are not guaranteed to be compatible based on their names alone; check specific fields such as TLS and the WebSocket path too.
Best for: nodes explicitly documented as supporting V2Fly, or when testing an existing V2Fly configuration.
After changing the Core type, restart the affected connection and check the startup log. The selected option in the interface may not immediately match the core that is already running, so do not assume the change has taken effect just by looking at the settings window. For help understanding the configuration layers, see the inbound, outbound, and routing sections in the JSON configuration guide.
Test the Connection: Check the Local Port, System Proxy, and Routing Separately
The local listening address is where apps connect to the client; the remote server port is where the core connects to a node. They are not interchangeable. The example 127.0.0.1:10808 is for checking a port only. Use the listener settings under Settings → Parameter Settings and the logs to confirm the actual port and protocol. Builds may offer SOCKS, HTTP, or a mixed listener.
| Check | What to verify | Common misinterpretation |
|---|---|---|
| Local listener | The log confirms the listener started successfully, and the expected process owns the port. | Assuming the client is running correctly just because a port is occupied |
| Active node | The node is selected as the active server, and the core has loaded its configuration successfully. | Assuming the connection works just because the subscription list has entries |
| System proxy | The system proxy points to the actual HTTP or mixed listener. | Entering a SOCKS-only port as an HTTP proxy |
| Routing rules | Confirm that test requests use the proxy or connect directly as expected. | Mistaking direct connections caused by bypass rules for a broken system proxy |
On Windows, check the example port in Command Prompt. The last column is usually the process ID. If another client is using the port, identify the process before exiting the conflicting app normally or changing the local listener port. Do not terminate an unfamiliar system process.
netstat -ano -p tcp | findstr ":10808"On macOS, use Terminal to check which process is listening on the example TCP port. No output only means the command found no matching listener. Check the actual client port and logs too; it does not mean the subscription is unavailable.
lsof -nP -iTCP:10808 -sTCP:LISTEN- If you change the local listening port, reapply the client’s system proxy settings and update any proxy address entered manually in browsers or other apps.
- On Windows, check the system proxy under Settings → Network & Internet → Proxy. On macOS, check Proxy under Details for the active network service.
- Not every app follows the system proxy. For your first test, use a browser that does, and avoid adding TUN or a browser proxy extension at the same time.
- Clear the system proxy before exiting the client. Otherwise, the system may keep sending requests to a local port that is no longer open.
v2rayN Setup FAQ
Nothing happens when I double-click after extracting. Should I reinstall?
First make sure you are not running the app from inside the archive, then check for runtime or architecture errors. On Windows, check Windows Security → Virus & threat protection → Protection history for related entries. On macOS, confirm that the app is in a permanent location and meets the system requirements. Address the specific error instead of repeatedly replacing the package with builds for different architectures.
A subscription update timed out. Which setting should I check first?
First check that the subscription URL has not expired, the system date and time are correct, and your current network can reach the subscription server. Try updating through the proxy only if you already have a working node. Relying on a proxy update before importing any usable node can create a loop that prevents the initial import. For certificate errors, check the system time and certificate chain; do not disable certificate validation by default.
The node latency test succeeds, so why won’t webpages load?
A latency result only confirms that the relevant test completed; it does not mean your browser is using the local proxy. First check that System Proxy is set to Set system proxy automatically, then check the active node and core logs. If the browser has a manual proxy configured, confirm that its protocol and port match and temporarily remove any duplicate proxy settings.
Why does my internet stop working after I close the client?
Open your system proxy settings and check whether they still point to 127.0.0.1. If the local client has exited, turn off any leftover manual proxy setting, or restart the client and select Clear system proxy. Do not reset all network settings instead of checking this first.
Do I need to enable launch at login and TUN right after installation?
Neither is required for your first connection. First complete this cycle: start the core, set the system proxy, open a webpage, then clear the system proxy. Once the basic connection is stable, enable launch at login if you need it. Configure TUN separately only if an app you need does not follow the system proxy, and address any required permissions.
What to Keep and Recheck After Setup
After your first successful connection, keep a record of the working core, listening port, and routing setup. When troubleshooting later, change one variable at a time: check whether the app starts, then review the core log, test node connectivity, and finally check whether the app is using the proxy. This makes it easier to distinguish changes in the installation environment, an unavailable node, and leftover system settings.
- Record the essentials: Note the client version, package architecture, active core, and port locally. Do not share subscription URLs or node credentials.
- Quit before backing up: Exit the client normally before copying its configuration to avoid capturing files while they are being written. Configuration files may contain sensitive information; store them securely.
- Read update notes: When changing interface types or upgrading across major versions, do not assume you can overwrite the old directory wholesale. Keep a recoverable copy of your configuration first.
- Check what happens on exit: Confirm that the system proxy is cleared when you quit normally and that regular network access works as expected after restarting your computer.
To learn more about importing subscriptions and configuring routes, follow the Getting Started guide. The goal of a first installation is a basic setup you can understand and verify, not enabling every feature at once.