v2rayN for Windows: Installation and Setup Guide | WPF vs. Cross-Platform Desktop Edition

Choosing between the WPF and cross-platform desktop editions

v2rayN manages nodes, subscriptions, and proxy settings; the proxy core associated with your configuration handles the actual connection. The WPF and cross-platform desktop editions differ primarily in their interface technology and supported environments, not in proxy protocols. Whether a node works depends on the core, configuration parameters, and server status—not just the interface edition.

Do not extract both editions to the same folder or enable the system proxy or TUN in both at once. Before testing the other edition, clear the system proxy and exit the current app from the system tray. This prevents configuration conflicts and makes it clear which process is listening on each port.

Check your system architecture and extract to a writable folder

In Windows, open Settings → System → About and check System type. Most Intel and AMD desktop PCs use the x64 package. For ARM devices, check architecture support on the download page and in the release notes; “64-bit” alone is not enough to identify the right package. Find all downloads on the Download clients page.

1. Check the package

   Make sure the package is for Windows and matches your architecture and preferred edition—WPF or cross-platform desktop. If you downloaded an installer, follow its setup wizard. If you downloaded an archive, extract it using the steps below.

2. Extract all files

   Extract the entire archive to a permanent folder that your account can write to, such as Apps\v2rayN in your user folder. Do not run the app from your archive utility's preview window.

3. Keep the files together

   Keep the main program, bundled configuration, and core-related folders in their original layout. Copying only v2rayN.exe to your desktop can leave it without required dependencies or core files. Create a shortcut if you want quick access.

4. First launch

   Start the app as a standard user and leave TUN disabled for now. Once the main window opens, check the logs for configuration write failures, missing files, or core startup errors.

App won't start? Check the runtime message first

A double-click that opens no window does not mean the node is unavailable. The app may not have reached the connection stage at all. Check whether it is minimized to the system tray, missing a runtime, incompatible with your system architecture, or blocked by security software. Open Task Manager to see if a v2rayN process is already running, then check the taskbar's notification area.

Runtime requirements can change between releases, so avoid relying on a major version number copied from an old guide. A self-contained package with a bundled runtime works differently from one that depends on a system runtime. Follow the startup message and release notes for your package. Restart the client after installing the runtime and check whether the error persists.

Importing your first subscription: update it, then activate a node

A subscription URL and a single-node share link are different kinds of input. A subscription is usually an HTTPS URL that retrieves a list of nodes; VMess and VLESS share links describe individual configurations. Pasting a webpage URL, login page, or text with extra instructions into the subscription field can leave the node list empty after an update.

1. Create a subscription group

   In the main window, open Subscription Groups → Subscription Group Settings, then choose Add or “+”. Enter a name that will help you recognize the group, paste the full subscription URL into the address field, and save. Some interface versions place this option under a group management button; look for the same function name.

2. Update the subscription

   If this is your first setup and you do not have a working proxy yet, choose Subscription Groups → Update All Subscriptions (without proxy). If the URL is only accessible through a proxy, set up a working configuration first, then choose Update All Subscriptions (through proxy).

3. Check the node list

   Check the update log for a successful result and make sure the newly created group is selected. If the list is empty, check whether the subscription has expired, returns a login page instead of node data, or is hidden by a group filter.

4. Activate a node

   Select the node you want to use, then choose Set as Active Server from the right-click menu. Check the logs to make sure the associated core starts, then test the connection. Selecting a row in the list does not necessarily activate it.

Subscription URLs often contain account access tokens. Do not post them in public chats or share screenshots that show the full URL with strangers. When troubleshooting, record the error message, protocol, and update time instead. Before sharing client logs, remove any node addresses or user identifiers they may contain.

Node test results are only clues. A successful TCP connection does not confirm that TLS, authentication, and subsequent requests work. A timeout may also mean the test target is unreachable. After activating a node, check the logs and try an actual web request instead of switching nodes based only on latency.

System proxy setup: check the local listening port first

Open Settings → Parameter Settings and check the local listening ports and their inbound protocols. The three numbers below are examples for identifying settings; not every release listens on all of these ports. Do not copy an HTTP port from an old guide into a newer release. Use the values shown in your current settings and startup logs.

• Make sure the node is set as the active server and the core logs show no startup errors.
• In the main window or the tray icon's right-click menu, open System Proxy and select Automatically Configure System Proxy. The menu location can vary, but this option writes the proxy settings to Windows.
• In Windows, open Settings → Network & Internet → Proxy and check that the address and port point to the local HTTP or mixed listener provided by the client.
• If a browser extension manages proxy settings separately, set it to follow the system settings so it does not override the Windows proxy.
• Visit a website and check the client logs. Before exiting the client, select Clear System Proxy.

Automatically Configure System Proxy does not mean every app will use the proxy or that the fastest node will be selected. Apps that follow the Windows system proxy will use this setting; others may connect directly. Client routing rules determine whether requests that reach the core use the proxy or connect directly.

Port conflicts and permission errors: troubleshoot by symptom

If the logs show address already in use or a bind failure, check the listening port before deleting any configuration. Common causes include an older process still running in the system tray or another client using the same port. The commands below only check local TCP listeners; they do not change network settings.

netstat -ano -p tcp | findstr LISTENING | findstr ":10808"
tasklist /FI "PID eq 1234"

The last column in the first command is the PID. In the second command, 1234 is an example; replace it with the PID returned by the first command. Confirm that the local address is using port 10808 before checking what the process does. Do not end a process just because its output contains the same number.

• Another v2rayN instance is running: Exit it from its system tray menu, confirm the port is free, and then start the current version. Do not let two instances compete to manage the system proxy.
• The port is used by a required app: Open Settings → Parameter Settings and change the local listening port to an unused one, such as 10818. Confirm the port is free, save the setting, and restart the relevant core.
• Still can't connect after changing the port: Apply the system proxy settings again, and update any browser extensions or terminal tools that specify the port manually. If only the client setting changes, other apps will still use the old port.
• The port is free, but access is denied: Check system-reserved ports, security policies, and endpoint protection logs. Standard port listening and TUN elevation are separate issues; do not run the app as an administrator all the time as a workaround.

Verify your setup and back up before upgrading

Check startup, proxy behavior, and shutdown. Loading a webpage once only confirms that one request worked at that moment. Also make sure closing the client does not leave a broken proxy setting behind and that your configuration is restored after a restart. Following the checklist below makes later changes easier to pinpoint.

1. Check startup: Exit and reopen the app. Confirm that the subscription group, active node, and local port are still set, and that the logs show no repeated core startup failures.
2. Check the proxy: Enable the system proxy and visit sites that should use the proxy as well as sites that should connect directly. Use the logs to verify routing; a cached webpage alone does not prove the connection is working.
3. Check shutdown: Clear the system proxy before exiting, then confirm that your regular network connection still works. If the app closes unexpectedly, check Windows proxy settings and remove any leftover manual proxy.
4. Back up your settings: Exit the app before upgrading and back up the current version's user settings and subscription groups. For a portable setup, back up the entire folder; for an installed version, back up the data from its actual user data location.
5. Check migration: When switching editions, use the client's built-in import and export features if available. If there are no clear migration instructions, import your subscriptions again and verify key settings. Do not merge the two application folders by copying one over the other.

Backups may contain subscription tokens and node credentials, so store them somewhere only you can access. If only the interface is acting up after an upgrade, keep the logs and original backup, then check the release notes. If webpages won't load, troubleshoot in this order: local listener, system proxy, and node logs. For basic steps, see Quick Start; for more complex connection issues, visit Troubleshooting.