v2rayN for Windows: Install Guide and WPF vs. Cross-Platform Edition

Compare the two v2rayN editions for Windows and learn how to choose, install, and troubleshoot common issues such as missing runtimes, antivirus alerts, and startup settings.

At a glance

For Windows-only use and the classic interface, choose the WPF edition. To keep a similar workflow across desktop operating systems, choose the Windows package of the cross-platform edition. For a fresh install or an upgrade, check three things: the main window opens, the core listens on a local port, and only the intended copy starts after you sign in.

Choosing between the WPF and cross-platform editions

The WPF and cross-platform editions differ in their UI framework, packages, and runtime requirements—not in proxy protocols. Whether configurations using VMess, VLESS, and other protocols work depends on the selected core, its version, and the configuration itself. If a protocol error occurs, check the core logs first rather than blaming the UI edition.

WPF edition

Recommended

Uses a Windows-specific WPF interface. If you’re used to the classic layout, choose the WPF package that matches your system architecture. Check the package notes and startup prompts to see whether you need to install a runtime separately.

Best for: Windows-only use or migrating from the classic interface.

Cross-platform edition

Offers a similar interface across desktop operating systems, but you still need the Windows package for Windows. Cross-platform does not mean one file runs on every system, or that you can use an older edition’s configuration folder as-is.

Best for: switching between desktop operating systems or using the newer layout.

In Windows, go to Settings → System → About and check System type. Choose x64 if it lists an x64-based processor and a 64-bit operating system. On ARM devices, check whether an ARM64 package is available. x64 and ARM64 are not interchangeable just because both are 64-bit.

Install and extract: choose a permanent app folder

If the download is an installer, follow its setup steps. If it’s an archive, extract all files using File Explorer. Don’t launch the app from the archive preview, and don’t just drag v2rayN.exe onto your desktop. The main app and the core may rely on different files. Missing files can leave the interface working while connections fail after you select a node.

  1. Choose a permanent location

    Enter %LOCALAPPDATA% in File Explorer’s address bar, then fully extract the portable package to its own folder, such as %LOCALAPPDATA%\Programs\v2rayN-WPF. Don’t put a portable package that needs to write configuration files in a protected system folder or a synced drive. Create a shortcut on your desktop instead.

  2. Check for old processes

    If v2rayN is already installed, first clear any system proxy settings configured by the old edition from its tray menu, then exit it. Closing the window may only minimize it to the tray. If needed, open Task Manager → Details and make sure the old v2rayN.exe process has exited.

  3. Launch the app

    Open v2rayN.exe from the new folder, or use the shortcut created by the installer. Confirm the interface opens normally before importing a configuration. If Windows reports a runtime error, note the full framework name, version, and architecture, then follow the next section.

  4. Check the local port

    In the main window, open Settings → Parameter settings and check the local listening port. Some versions list it under Core: Basic settings. Select an existing, usable configuration, check the core logs for port conflicts, and then verify that the port is actually listening.

Won’t open? Check for missing runtimes or security blocks

If an error says you need to install or update .NET, check the Framework, Version, and Architecture fields. If the main app opens but reports a missing core file only after you enable a configuration, first check that the archive was fully extracted, that the package includes the required core, and that the file hasn’t been quarantined. These are different issues and need different fixes.

Missing .NET runtime

Framework
Microsoft.WindowsDesktop.App requires the .NET Desktop Runtime
Version
If the error specifies 8.0.0, install a supported 8.0 servicing release. Don’t assume a newer major version is a substitute.
Architecture
Choose the value shown under Architecture in the error dialog, such as x64; don’t rely on your OS bitness alone.

Get the matching runtime from an official Microsoft source. Restart the app after installation. If the error persists, check the message again to identify the missing framework.

Threat alert after download

Where to look
Windows Security → Virus & threat protection → Protection history
What to check
Expand the entry and review the detection name, affected file path, and action taken.
What to do
Keep the file quarantined and verify the download source and package. If the source is unknown or the alert persists, stop using the file.

If you suspect a false positive, submit the file to your security software provider for review. Don’t disable real-time protection or add the entire app folder to exclusions.

If the alert names Microsoft.NETCore.App, it refers to the .NET Runtime. If it names Microsoft.WindowsDesktop.App, installing only the base .NET Runtime of the same version won’t be enough. If there’s no error dialog or quarantine record, open Event Viewer → Windows Logs → Application and look for .NET Runtime or Application Error entries from the time you tried to launch the app. Note the faulting module and error code before deciding whether to install a dependency or download the package again.

The interface opens, but websites don’t: troubleshoot the ports step by step

First check whether the core started, then check whether the app is routing requests through the proxy. This example uses 127.0.0.1:10808; check the current version’s settings and logs for the actual port. If the interface lists separate HTTP and SOCKS ports, match both the protocol and port when configuring an app manually. Don’t just pick whichever port responds.

127.0.0.1
The loopback address for testing on your own computer
10808
Example local listening port; verify the configured value before testing
8.0
Example runtime major version; requirements vary by package
Test-NetConnection -ComputerName 127.0.0.1 -Port 10808
Get-NetTCPConnection -LocalPort 10808 -State Listen |
  Select-Object LocalAddress, LocalPort, OwningProcess
  • TcpTestSucceeded : False: The TCP probe couldn’t connect to this address and port. Check the port number, then review the core logs for configuration or listening errors. You don’t need to change your subscription yet.
  • TcpTestSucceeded : True: A local TCP connection to this address and port succeeded; this doesn’t mean the remote server is reachable. To check whether an old instance is using the port, look up OwningProcess and match its PID in Task Manager → Details to identify the process.
  • Once you’ve confirmed the expected core is listening, check the System proxy setting in the tray menu. Browsers using the system proxy and apps configured with their own proxy may take different routes. If websites that normally connect directly stop working after you exit v2rayN, check whether Windows Settings → Network & Internet → Proxy still points to a local port that is no longer active. For managed proxy settings, check with your administrator first.

If the local port and system proxy are working but only certain destinations fail, continue with connection troubleshooting, using the core logs and symptoms to narrow down the cause.

Startup, tray behavior, and upgrade FAQs

Why doesn’t a window appear after I enable launch at startup?

First check the taskbar’s hidden icons for v2rayN, then look for its process under Task Manager → Details. If the tray icon appears after sign-in but the main window doesn’t, the app is probably starting minimized. If the process isn’t running, open v2rayN’s Settings → Parameter settings, turn Launch at startup off and back on, save, then sign out and sign back in to test. This applies to startup after a user signs in, not to running as a system service before sign-in.

Why does the old edition still launch after I move the app folder?

Turn off startup in the old edition and exit it, then enable startup in the new one. If you previously created a startup shortcut manually, press Win + R, enter shell:startup, and check the shortcut’s Target. Remove only the shortcut you’ve confirmed points to the old folder. After signing in again, right-click the process in Task Manager, choose Open file location, and verify the path.

Do I need to run as administrator for every update?

For everyday use, launch the portable package as a standard user. If you get a write-access error, check that the app and configuration folders are writable, then move the package into your user folder if needed. If a runtime or installer requests elevation, follow the prompt only if you trust its source. Don’t permanently set the main app to run as administrator just to work around folder permissions.

The list is empty after an upgrade. Has my subscription expired?

First check which copy of the app you launched. An empty window in the new folder may simply be reading a different configuration. Exit the new edition and check whether the list and subscription groups are still present in the old one. If an export or backup feature is available, use it to migrate; otherwise, import again from a trusted source. After migrating, verify the groups, selected configuration, and local port before removing the old folder.

Download the client