v2rayN for Windows: Installation, Setup, Desktop vs. WPF, and Common Issues

Desktop vs. WPF: Choose the UI, Then Check Your Architecture

v2rayN is a desktop client whose interface manages subscriptions, generates configuration, and controls proxy settings. The bundled core handles connections. When a download page offers separate “Desktop” and “WPF” builds, Desktop usually refers to the Avalonia-based interface, while WPF uses Windows’ WPF UI framework. Check the package details to confirm what is included; do not rely on the label alone.

The UI framework does not determine which protocols are supported or how fast a connection will be. Whether either build can use a VLESS or VMess configuration depends on its bundled core, core version, and full set of parameters. Switching builds will not fix an incorrect server address, UUID, transport path, or REALITY settings.

Open Windows Settings → System → About and check “System type.” Choose an x64 package for an x64 system; for an ARM64 device, choose a package explicitly marked ARM64. Architecture is a prerequisite, while Desktop vs. WPF is a separate choice—do not confuse the two.

Extract All Files and Install Required Runtimes

Extract the entire archive before launching the app. Opening the executable directly inside an archive may extract only some files temporarily, leaving the core, resource folders, or configuration database unavailable. Use a regular folder where you have write access, such as D:\Tools\v2rayN. If you do not have a D: drive, use a tools folder under your user directory.

1. Check the architecture

   Go to Settings → System → About and check whether your system is x64 or ARM64. Choose the matching Windows package from the download page, and note whether it is the Desktop or WPF build.

2. Extract the entire archive

   Extract every file in the archive to a dedicated folder, then run v2rayN.exe from there. Keep the original folder structure; do not copy only the executable.

3. Install required runtimes

   If a prompt asks you to install .NET, note the framework name, version, and architecture. For a framework-dependent WPF package, install the required Desktop Runtime. An SDK or a different runtime is not a substitute.

4. Check that it starts

   Launch the app normally and confirm that the main window and log area are available. Leave TUN and startup options disabled for now so you can rule out folder permissions and incomplete files first.

Import and Update Subscriptions

Installing v2rayN does not give you working nodes by itself. A subscription link usually points to a list of configurations and may contain access credentials. Use only links you are authorized to access and whose source you trust. Do not share the full link in public screenshots or support requests.

The steps below use common labels from the Chinese-language interface. Depending on the build, the same options may appear in a menu bar or toolbar, and button text may differ slightly. Look for the “Subscription Group” and “Update Subscription” functions. Do not paste a full subscription URL into a single server’s address field.

1. Add a subscription group

   Open Subscription Group → Subscription Group Settings → Add. Enter a descriptive name, paste the full subscription URL into the URL field, and save.

2. Update it for the first time

   From the Subscription Group menu, select “Update All Subscriptions (without proxy).” If you do not have a working proxy yet, first check whether your current network can reach the subscription service directly.

3. Check the server list

   After updating, confirm that server entries appear under the intended group. If the update reports success but the list is empty, check the group filter, subscription format, and whether the server returned a login or error page.

4. Set an active server

   Right-click the target entry in the server list and select “Set as Active Server,” then check the core logs. Importing entries and activating a configuration are separate steps; a successful subscription update does not prove that a connection works.

If you already have a verified working configuration and the subscription URL is reachable only through a proxy, select “Update All Subscriptions (through proxy).” Repeatedly switching this option without a working connection will not fix an invalid URL, expired access token, or server error. Keep the VLESS, VMess, and transport security values provided by the subscription; do not change protocols just to “improve compatibility.”

System Proxy: Test a Browser Connection First

For your first setup, enable only the system proxy. It directs apps that follow Windows proxy settings to a local listening port; it does not route traffic from every app. In the system tray, choose System Proxy → “Set system proxy” to write the proxy settings to Windows. “Set system proxy” does not guarantee every site will use a remote node—the client’s routing rules still determine where traffic goes.

The three values below are for identifying what to check on your local machine. They are not defaults for the current version or ports on a remote server. Use the commands later in this guide as written only if your actual settings match these values.

Correct values on the Windows proxy page do not prove that the core is running. The active configuration must be valid, the core must be running, and the local port must be listening. Browser extensions can also set a separate proxy. During troubleshooting, configure the browser to use the system proxy so the two settings do not point to different ports.

TUN and Routing: Expand Traffic Capture Only When Needed

TUN uses a virtual network interface to capture traffic and can help with apps that ignore the system proxy. It is still affected by routing, DNS, app behavior, and permissions, and is not a universal network fix. First verify that the same node works through the system proxy, then test TUN to distinguish a node issue from a local traffic-capture issue.

• Record a baseline: Note the active configuration, local ports, and routing mode, and keep a copy of settings you can restore. Change only one variable at a time while troubleshooting.
• Test separately: In the system tray, choose System Proxy → “Clear system proxy” to remove the browser proxy settings for this test, then enable “TUN” in the main window. They do not always have to be used separately; testing them one at a time makes it easier to identify the traffic path.
• Handle permissions: If the client asks for elevated permissions, follow the prompt to restart and grant them. Administrator access addresses only some startup requirements; check the logs for virtual interface issues, route conflicts, or missing components.
• Check routing: Confirm the selected rule set in the main window’s routing options. Domains, IP addresses, rule order, and the final outbound determine where traffic goes. Labels such as “Global” or “Bypass” do not tell you the route for every connection.
• Restore settings after testing: Disable TUN and confirm that regular network access works again. To switch back to the system proxy, re-enable the relevant option. Do not change DNS, routing, and nodes all at once and then guess which change mattered.

Common Windows Errors: Check Ports and Logs

Start troubleshooting in the main window’s log area. Note when the issue occurred and capture the first specific error. The final “startup failed” or “connection failed” message often omits the cause. Before sharing logs, remove subscription tokens, UUIDs, server addresses, and other sensitive information. Do not post a full configuration as a regular attachment.

Run these commands in PowerShell. Assuming the actual HTTP listening port is 10809, check whether it is listening, then send a request through the explicit proxy. example.com is only a sample destination. For testing, use an address you are allowed to access and whose status you know, and check whether the request uses the proxy outbound.

# Check the example port and the PID of its process
netstat -ano | findstr :10809

# Use the local HTTP proxy explicitly to rule out whether the app honors system proxy settings
curl.exe --proxy http://127.0.0.1:10809 --connect-timeout 10 --max-time 20 -I https://example.com

# After exiting the client, check whether a direct connection still works
curl.exe --noproxy "*" --connect-timeout 10 --max-time 20 -I https://example.com

LISTENING only means a process is listening; it does not prove that the process is the current v2rayN core. Use the PID in the output to check the Details tab in Task Manager. An HTTP response means the request received a response, not necessarily that it went through a remote proxy; check the routing logs. For a refused connection, check the local listener first. For a handshake error, verify the protocol parameters and system clock.

Upgrade and Migration: Keep Configurations, Avoid Mixing Files

Before upgrading, confirm that the current setup works and back up your configuration. When switching between the Desktop and WPF builds, using a separate folder makes it easier to roll back than overwriting the existing one. Configuration formats, database locations, and migration options can vary between builds. After a new version has written data, do not assume an older version can safely use the same files.

1. Record the current setup: Save the app’s version, package type, local listening ports, active routing mode, and TUN status. Record what is actually configured rather than assuming the latest versions all work the same way.
2. Exit before backing up: Clear the system proxy, disable TUN, and exit the app normally. For a portable package, back up the entire extracted folder. If user data is stored separately, back up that location as described for your build.
3. Test in a new folder: Extract the new package in full and restore the configuration using the import or migration instructions for that version. First test a known working node, then check subscription updates, system proxy, and TUN.
4. Enable startup last: Once everything is working reliably, enable launch at startup if needed. If the app opens at startup but TUN fails, check permissions and startup logs; adding duplicate startup entries will not fix it.

Installation is not complete just because the app opens. You should know which runtimes the package needs, which configuration is active, which port handles traffic, and how to restore system settings when you exit. Follow this sequence to narrow down later issues with subscription updates, core errors, or routing.