Complete v2rayN Windows Installation and Setup Guide: How to Choose Desktop or WPF and Fix Common Errors

Choose Desktop or WPF before installing

Windows builds of v2rayN may offer both Desktop and WPF interfaces. Both handle configuration, subscription updates, routing, traffic splitting and core control. Support for VMess, VLESS, Trojan, Shadowsocks, REALITY and other protocols mainly depends on the selected core and its version, not the interface name.

The WPF edition uses Windows Presentation Foundation and behaves more like a traditional Windows desktop application. It suits users who work exclusively on Windows and prefer classic tray menus and window controls. The Desktop edition uses a newer desktop interface with a layout closer to other desktop environments, making it a good choice for users who prefer the newer design or want a consistent workflow.

A package name containing SelfContained usually means the required .NET runtime components are included. The download is larger, but it avoids startup failures caused by missing runtime files. Packages without this label are smaller and require a matching .NET Runtime or .NET Desktop Runtime to be installed first. Always follow the dependencies listed on the download page and in the startup message.

Download, extract and launch for the first time

v2rayN is usually distributed as a compressed archive. After downloading it, extract the entire archive before launching the main executable. Do not double-click the program from a compression tool’s preview window: if the core, language files and configuration folders have not been fully extracted, the process may appear briefly and then exit.

Place the program in a fixed folder where the current account has full read and write access, such as D:\Apps\v2rayN. Keep the path short and avoid system directories that require administrator permissions for writing. Core updates, log files and saved settings will all use this folder.

1. Choose a package

   Open the package download page on this site and choose the Windows x64 Desktop or WPF build that matches your system. If you are unsure about runtime requirements, choose a package marked SelfContained.

2. Extract the complete archive

   Right-click the archive and choose “Extract All”. You can use D:\Apps\v2rayN as the destination. Make sure the main executable, core directory and resource files remain in the same extracted folder.

3. Unblock the files

   If the archive properties show an “Unblock” option, select it before extracting. If the extracted files are still blocked, unblock the original archive and extract it again.

4. Launch the main program

   Double-click v2rayN.exe, then check the notification area after the first launch. Closing the window usually leaves the program running in the tray; it does not necessarily mean the program has exited.

5. Check the core

   Open “Settings” → “Parameter Settings” and make sure the core type matches the node protocol. VLESS and REALITY configurations generally require an Xray core that supports the relevant fields.

After the first launch, open “Settings” → “Parameter Settings” to check the interface language, startup behavior, log level, local listening ports and core type. After changing the core type or an important port, stop the current core and restart the node so the newly generated configuration is loaded completely.

Import a subscription and make the first connection

A subscription URL and an individual share link use different entry points. A subscription URL usually returns a refreshable set of server configurations and belongs in a subscription group. Content beginning with vmess://, vless://, trojan:// or ss:// usually represents an individual share link that can be imported in bulk from the clipboard.

To add a subscription, open “Subscription Groups” → “Subscription Group Settings”, create a group, and enter its name and subscription URL. After saving, use “Subscription Groups” → “Update All Subscriptions (without proxy)” for the first fetch. If the subscription service is reachable only through an existing proxy, connect to a working node first, then use the update option that goes through the proxy.

1. Create a group

   Open “Subscription Groups” → “Subscription Group Settings”, click Add, enter an easy-to-recognize note, and paste the complete subscription URL.

2. Update the list

   After saving, choose “Subscription Groups” → “Update All Subscriptions (without proxy)”. When the update succeeds, the main list will show server addresses, ports, protocols and transport methods.

3. Choose a node

   Select a node in the main list and set it as the active server. Run an actual latency or connectivity test first; do not use a timed-out node for subsequent system proxy checks.

4. Enable the system proxy

   From the tray menu or the system proxy option in the main window, choose “Auto Configure System Proxy”. Confirm that the tray status changes before testing in a browser.

For an individual share link, copy it to the clipboard and use the clipboard import function under the “Server” menu. After importing, check the address, port, user ID, transport, TLS, SNI, fingerprint and Flow. For VLESS with REALITY, also verify that the public key, Short ID, Server Name and server-side settings match.

Configure the system proxy, ports and TUN mode

System proxy mode and TUN mode solve different problems. System proxy mode points Windows proxy settings to v2rayN’s local listening port, so browsers and applications that follow the system proxy use the node; programs that ignore system proxy settings may still connect directly. TUN mode uses a virtual network interface to capture a broader range of traffic and is useful when non-browser applications also need the proxy.

In common configurations, the local SOCKS port may be 10808 and the HTTP port may be 10809. Some newer configurations use one mixed port for both types of requests. Do not rely on port numbers alone: open “Settings” → “Parameter Settings” to see the actual listening values, then compare the address and port with the Windows system proxy settings.

If a browser can open web pages but a desktop application cannot connect, first check whether the application supports reading Windows system proxy settings. If it accepts only a SOCKS address, enter 127.0.0.1 and v2rayN’s current SOCKS port in the application’s own network settings instead of entering the remote server address.

Before enabling TUN mode, use the system proxy to verify that the node itself works. Then enable the virtual network adapter through v2rayN’s TUN entry and follow the permission prompts. If TUN fails to start, check for other virtual adapters, network tools using overlapping routes, and Windows security policies that may block driver or network configuration changes.

How to handle startup failures and core errors

When troubleshooting, open the logs first instead of relying only on latency results in the main list. In the log window, restart the active server and identify the stage where the error occurs: before the GUI loads, when the core process starts, when a local port is bound, during DNS resolution, or when the remote handshake is rejected. Each stage requires a different fix.

If the error occurs only during subscription updates, distinguish HTTP status errors from connection timeouts. A 401 or 403 response usually indicates expired subscription credentials, an access policy restriction or a truncated URL; 404 usually means the path has changed. A connection timeout requires checking DNS, the current network and whether the update must go through a proxy.

If the core starts but every node times out, compare two different server addresses first, then check the system clock. TLS and REALITY handshakes depend on a reasonable local time, and a large Windows clock offset can cause handshake failures. After synchronizing the time, stop the old core process completely and try again.

System proxy failures, missing tray icons and upgrade issues

When the system proxy does not work, first confirm that the v2rayN core is running, then confirm that an active server is selected, and finally check that the Windows proxy address points to 127.0.0.1 and the current HTTP or mixed port. If the proxy switch still uses an old port, choose Clear System Proxy from the tray menu and enable automatic configuration again.

A missing tray icon does not necessarily mean the program has exited. Windows may place it in the notification area’s overflow menu, or tray display may be disabled for the application. Expand the hidden icons on the right side of the taskbar, then open Windows taskbar settings and make v2rayN’s notification icon visible. If v2rayN is already listed in Task Manager, do not repeatedly double-click it to launch multiple instances.

Do not overwrite files while v2rayN is running. Exit the tray program first, copy the old directory as a backup, and extract the new version into a separate directory. After launching the new version, check subscription groups, routing rules, custom DNS, core type and local ports before handling the old directory.

• The subscription updates but nodes will not connect: check node fields, system time, core version and remote network status.
• The node connects but the browser cannot access the web: check the system proxy switch, local listening address, port and browser proxy policy.
• The browser works but other applications connect directly: check whether the application reads system proxy settings; if necessary, enter SOCKS settings separately or test TUN.
• Settings are lost after a restart: check write permissions for the program directory and make sure you did not launch a copy from another extracted directory.
• The same port remains occupied: close duplicate instances, confirm in Task Manager that the old core has ended, then start again.

Basic checks after installation

A successful installation should not be judged solely by whether the window opens. Use this reproducible order: confirm the version and core type, update subscriptions, select an active server, inspect core logs, enable the system proxy, test browser access, and only then verify routing and TUN. If a step fails, stop at that layer and fix it before changing the protocol, DNS, port and core at the same time.

Configure routing only after basic connectivity is stable. Rules usually decide whether traffic uses the proxy, connects directly or is blocked based on domains, IPs, processes or ports. After adding a rule, check the matching order: place specific rules before general ones so broad conditions do not capture traffic first.