How to Install and Set Up v2rayN on Windows: Desktop vs. WPF

Compare v2rayN’s Windows desktop and WPF editions, then follow the steps to extract, launch, import a subscription, and configure the system proxy. Troubleshoot antivirus alerts and port conflicts.

At a glance

Setting up v2rayN on Windows for the first time? Choose a package that matches your system architecture and runtime, then check that the client launches, the subscription updates, a node is selected, and your apps are using the system proxy. The same sequence works when migrating from an older version. Change one thing at a time to pinpoint problems.

Choosing between the desktop and WPF editions

Here, “desktop” refers to the edition built with a cross-platform UI framework, while the WPF edition uses a Windows-specific interface. Menus, windows, and tray interactions may differ. The interface does not determine which protocols are supported: node compatibility depends on the core and configuration in use, not the package name.

Desktop edition

Recommended

For a first-time setup, start with the desktop edition that matches your system architecture. If the release offers a self-contained package, it usually includes the required .NET runtime, so you won’t need to install it separately. Check that your system meets the release’s requirements.

Best for: A fresh Windows setup with no preference for the older interface

WPF edition

Choose this edition if you prefer the familiar Windows interface. If you download a framework-dependent package, install the matching .NET Desktop Runtime as indicated by the launch prompt and release notes. Check the major version and architecture; the standard .NET Runtime may not meet a WPF app’s requirements.

Best for: Users familiar with WPF or following instructions for a specific version

In Windows 11, open Settings → System → About and check “System type.” Choose the x64 package for an x64-based processor. For ARM devices, use an ARM64 package if the release explicitly provides one. “64-bit operating system” does not necessarily mean x64. “Self-contained” indicates whether the runtime is bundled; “includes core” indicates whether the proxy core is bundled. Check both when downloading.

Download, launch, and import a subscription

  1. Download the right package

    Open the Windows client section from the download page and choose a package for your architecture and preferred interface. Extract archives fully to a separate folder your account can write to. Don’t run the app from the archive preview or drag only the main executable to your desktop. Follow the installer for setup packages. To launch an extracted app from the desktop, create a shortcut.

  2. Launch for the first time

    Run v2rayN.exe from the extracted folder and check that the main window and tray icon appear. For a basic system proxy test, run the app without elevated privileges. If a runtime is missing, follow the error message. If the main window opens but the logs say the core can’t be found, check whether the package includes the required core; this is not a UI runtime issue.

  3. Save the subscription link

    In the main window, open “Subscription Group” → “Subscription Group Settings.” Select “Add” or the “+” button to create a group, give it a recognizable name, paste the full subscription URL into the address field, and save. Button locations vary by build. Subscription URLs often contain account tokens, so don’t share them in screenshots, public logs, or group chats.

  4. Update the subscription

    Select the group you just created, then choose “Update current subscription” from the “Subscription Group” menu. Saving the URL creates a group but doesn’t guarantee that nodes will appear. After updating, check the logs and the group’s list. If the list is empty, clear any search filters first, then check whether the logs show a failed request, an empty response, or a parsing error.

  5. Select a node

    Right-click the node you want to use and choose “Set as active server” or the equivalent option. Make sure the selected node appears in the interface. A successful subscription update only means the client retrieved the configuration; it doesn’t mean every node can connect. If the core reports an error after you switch nodes, check the logs before enabling the system proxy.

System proxy: test in a browser before considering TUN

Right-click the tray icon and select “Set system proxy” → “Auto-configure system proxy.” Some builds show this command directly in the tray menu. Then open Windows Settings → Network & Internet → Proxy and check that the manual proxy address and port point to the client’s local listener. If your organization manages proxy settings, note the existing values and follow its policies instead of overwriting them.

127.0.0.1
Local loopback address, not the remote node address
10808
Common local SOCKS or mixed-listener port
10809
Common HTTP listener port in older split configurations

These ports are examples to help identify settings, not fixed values to enter manually. In v2rayN, open Settings → Parameter Settings to check the local listener ports, and use the startup logs to determine whether the client uses a mixed or split listener. Windows manual proxy settings can’t point to a SOCKS-only listener. If an older guide specifies 10809 but your current version uses an HTTP-capable mixed port, use the port shown in the current settings.

Startup failures, subscription timeouts, and port conflicts

Did security software quarantine a file by mistake?

Open Windows Security → Virus & threat protection → Protection history and check the detection name, time, and exact path of the quarantined file. The main app and bundled core are separate files, so first identify which one was blocked. Don’t assume a detection is a false positive just because the app runs. Don’t disable protection or exclude the entire folder. If you can’t verify the file’s source or alerts keep appearing, stop running it and submit it for review.

The logs say a port is in use. What should I change?

Note the local listener port shown in the error. For example, to check who is listening on 10808, use PowerShell. Match the OwningProcess value in the output to the PID in Task Manager’s Details tab. If it’s an older v2rayN instance, exit it normally from the tray first. If another app is using the port, open Settings → Parameter Settings, change v2rayN’s conflicting port, and restart the core. Reapply the system proxy afterward, and update the port in any apps where you entered it separately.

Get-NetTCPConnection -State Listen -LocalPort 10808 |
  Select-Object LocalAddress, LocalPort, OwningProcess

Subscription updates are timing out. Will reinstalling help?

Check the subscription URL for missing characters or extra spaces, then retry “Update current subscription” from the “Subscription Group” menu. If you already have a working node, you can test the menu’s option to update through the proxy. If no nodes work, updating through the proxy won’t establish an initial connection. If the logs show HTTP 401 or 403, check your account and subscription access first instead of repeatedly changing local ports.

Why can’t I see my old groups after switching to WPF?

If you extracted the new edition to a separate folder, the new instance may not read the old instance’s configuration. Exit the old client and back up its configuration folder first, then add your subscription again in the new instance. Migrate manually added nodes separately. When moving across major versions, don’t overwrite the whole program folder; that could carry old cores and settings into the new version. Delete the old folder only after confirming the new instance can update subscriptions and start the core on its own.

Download v2rayN