Set up v2rayN in this order: choose an architecture and UI version → extract all files → install any required runtimes → import a subscription → select a server → configure the system proxy and routing. Desktop is a good starting point for Windows users; if your WPF setup already works, there’s no need to switch just to get online. This guide separates the UI, proxy core, and traffic routing, and covers port checks and startup troubleshooting.
WPF vs. Desktop: Choose the UI, Then Check the Core
v2rayN manages configurations and controls proxy connections; it is not a proxy protocol. The WPF edition uses Windows’ WPF UI framework, while the Desktop edition uses a cross-platform desktop UI. Layout, scaling, and some controls may differ, but connections depend mainly on the proxy core, server settings, network conditions, and server status.
Desktop edition
RecommendedFor a first installation, start with the Desktop edition. It suits users who want a similar workflow across desktop operating systems. Check the current Windows build notes for the exact feature set.
Best for: first-time setup and use across desktop operating systems
WPF edition
WPF is a Windows-specific UI technology. If your setup is stable and you know your way around the existing layout, you can keep using it—there’s no need to move your working directory just to change the UI.
Best for: Windows-only use and keeping your familiar workflow
VLESS and VMess are proxy protocols; Xray is a proxy core; WPF and Desktop are client UI editions. VLESS with REALITY requires a compatible core—switching UI editions won’t add protocol support. After importing a subscription, check each server’s requirements before changing core settings. Claims like “WPF is faster” or “Desktop supports every server” are no substitute for checking compatibility.
Windows downloads: architecture, runtimes, and extraction
Before downloading v2rayN, open Windows Settings → System → About and check System type; some Windows versions label this page System information. Most 64-bit Intel and AMD PCs use x64. For ARM devices, check the available builds and their requirements—64-bit alone doesn’t tell you which architecture to choose. See the download page for the current Windows packages available here.
Runtime requirements: two common build types
Self-contained build
- Includes the .NET runtime files needed to run that build.
- Keep the entire package directory; don’t copy only the main executable.
- The build must still support your version of Windows.
Build that relies on system runtimes
- Install the runtime matching the required major version and architecture shown in the startup message.
- WPF builds typically require the .NET Desktop Runtime.
- For Desktop builds, follow the included notes and any missing-framework prompt.
Whether v2rayN needs a separate runtime depends on how the build was packaged—not simply on whether it’s called WPF or Desktop.
If v2rayN is distributed as an archive, extract all files to a writable folder, such as D:\Tools\v2rayN\, before running v2rayN.exe from that folder. Don’t launch it from the archive preview or drag just the executable to your desktop. Keep the configuration, logs, and core-related files together. Create a desktop shortcut rather than moving the executable.
- Permissions: The system proxy usually doesn’t require running as an administrator. Grant permission when prompted for TUN, which may use a virtual network adapter or service.
- Runtimes: Check which framework the error message requests. Installing the SDK is not the first troubleshooting step for most users.
- Folder: Avoid locations without write access, and don’t let two versions write to the same configuration files.
- Security: Check where the download came from and review the specific Windows Security alert. Don’t disable protection entirely.
First launch: import a subscription and select a server
v2rayN does not include usable remote servers. Your service provider supplies the subscription URL, which typically contains a token that grants access to your account. Treat it like a password. The steps below use common labels from the Chinese UI. Menu names for subscription groups or updates may differ between releases, so look for the equivalent function rather than changing unrelated settings to match these labels.
-
Extract all files
Close any running instance, extract the archive to a separate folder, and run
v2rayN.exe. If Windows reports a missing framework, install the required runtime and restart the app. -
Add a subscription group
Open Subscription groups → Subscription group settings, add a group, enter a recognizable name, paste the full URL in the subscription address field, and save.
-
Update the subscription
Return to Subscription groups and select Update all subscriptions (without proxy). Use a direct connection for the first update, before you have a working proxy. Only try updating through a proxy if direct access fails and you already have a working proxy.
-
Select a server
Select a server in the list, right-click it, and choose Set as active server. Check that the active marker matches your selection, then look for core startup errors in the logs.
-
Connect your browser
From the main window or tray menu, open System proxy and select Automatically configure system proxy. Then check the current routing preset. For your first test, use a browser; there’s no need to enable TUN at the same time.
You can also import server share links provided by your service provider using Server → Import bulk URLs from clipboard. Unlike a subscription, an individually imported link won’t automatically refresh when the provider changes its server list. After importing, don’t change the VLESS UUID, REALITY public key, short ID, or server name without a reason—these values must match the server configuration.
System proxy and routing: start with a minimal setup
The v2rayN system proxy mainly affects apps that follow Windows proxy settings. Some command-line tools, games, and apps with their own networking stack won’t use it automatically. Routing presets choose an outbound route after traffic reaches the core: a global proxy rule generally sends traffic entering the proxy through the proxy, while rules that bypass mainland China generally send matching local destinations direct. The exact behavior depends on the rules and their order.
Test the connection first
- Active server
- Choose a server known to work
- System proxy
- Automatically configure system proxy
- Routing preset
- Temporarily use global proxy rules
- TUN
- Leave disabled for now
Reduce variables from split routing and virtual network adapters. Restore your usual routing after the test succeeds.
Everyday browsing setup
- Active server
- Use a server you’ve verified works
- System proxy
- Automatically configure system proxy
- Routing preset
- Choose rules that bypass mainland China as needed
- LAN access
- Turn off if you don’t need to share access
For a corporate network, check the domain and address rules to avoid routing internal traffic through a remote server.
In v2rayN, check the local listening port under Settings → Parameter settings, in the Basic or Inbound section; field groups vary by version. The example below uses 127.0.0.1:10808 as a confirmed mixed inbound for HTTP and SOCKS. It is not a universal default. If your configuration uses separate HTTP and SOCKS ports, replace the example port with the appropriate one.
# Check whether the example port is listening in PowerShell
Get-NetTCPConnection -State Listen -LocalPort 10808
# Test a website through a local inbound that supports HTTP
curl.exe --proxy http://127.0.0.1:10808 --max-time 15 -I https://example.com
# Test through a SOCKS inbound and resolve the domain through the proxy
curl.exe --proxy socks5h://127.0.0.1:10808 --max-time 15 -I https://example.comIf a command that explicitly uses the proxy gets an HTTP response but your browser still fails, check browser proxy extensions, browser settings, or the Windows proxy state. If nothing is listening on the local port, troubleshoot core startup or a port conflict instead of repeatedly switching remote servers. One HTTP response only confirms that specific request completed; it doesn’t prove that every site or app is using the proxy.
Common errors: troubleshoot by stage
When troubleshooting v2rayN, start with the earliest error. If the main window won’t open, check the runtime environment. If the window opens but no port is listening, check the core or inbound configuration. Only investigate server settings and network conditions once the local port is working but the remote handshake fails. Checking one stage at a time is usually more effective than reinstalling runtimes, switching cores, and changing DNS all at once.
| Symptom | Check first | What to do |
|---|---|---|
| Prompt to install or update .NET | Framework name, major version, x64 or ARM64 in the error message | Install the runtime required by the build. For WPF, distinguish the Desktop Runtime from the standard .NET Runtime. |
| Window closes immediately after launch | Whether all files were extracted, Windows is supported, and the folder is writable | Extract again to a separate writable folder. Check the logs or Windows event records; don’t overwrite the old configuration first. |
| Log shows address already in use | Whether another instance is using the local listening port | Use a port-check command to find the process, close the duplicate instance, or change the inbound port and update app settings to match. |
| Subscription update fails or server list is empty | Whether the URL is complete, the account is active, and the response is subscription data rather than a webpage | Check the client subscription format supplied by your provider. Distinguish direct updates from updates through a proxy, and never share your subscription token. |
| Server shows latency, but webpages won’t load | Active server, system proxy, and logs from an actual request | A latency test doesn’t confirm that a full proxy request works. Check the protocol handshake, DNS, and routing. |
| Browser can’t connect after v2rayN exits | Whether Windows still points to a proxy port that is no longer running | Restart the client and clear the system proxy. If needed, check Settings → Network & Internet → Proxy in Windows. |
For VLESS with REALITY, check the server address, port, server name, public key, short ID, and device time when certificate or handshake errors occur. Keep the system clock accurate for VMess as well. If subscription parameters have expired, update the subscription or ask your provider to confirm them; don’t hide a configuration error by disabling security checks.
If v2rayN opens, does that mean the core is working?
The v2rayN UI process and proxy core are separate components. If the main window opens, that only confirms that the UI’s runtime requirements are mostly met. Check the core startup logs and local listening port too. Missing core files, incompatible settings, or a port conflict can leave the UI working while the proxy is unavailable.
What if the browser works but terminal apps bypass the proxy?
After you configure the v2rayN system proxy, terminal tools may not use it automatically. First, confirm the proxy works with a test command that uses the --proxy parameter, then set the proxy address according to the tool’s documentation. Consider TUN only if you need to route traffic from more apps, and check its permissions, DNS, and routing separately.
Upgrading or switching editions: back up, then test
When switching v2rayN from WPF to Desktop or upgrading from an older release, test in a new folder first. Configuration formats may change, so don’t assume every version supports two-way compatibility. In the old version, note your subscription groups, active server, inbound ports, and custom routes. Then use the backup or migration method supported by the version you’re installing.
- Exit before backing up: Quit the old instance from the tray, confirm the proxy is restored, then back up the configuration folder. This prevents copying files while they’re being written.
- Use a separate folder: Keep all files from the new build together. Don’t mix or overwrite the app and core files from different versions.
- Test the basics: Import one subscription, select a server, check the port, and test a browser request before restoring complex routing rules.
- Keep a fallback: Retain the old folder until you’ve verified the new version, but don’t run two instances that use the same listening port.
- Redact sensitive details: When reporting an error, include the version, UI edition, system architecture, and relevant log lines. Hide subscription URLs, UUIDs, and account tokens.
A successful v2rayN installation means more than seeing the main window: the active server is clear, the core is listening, test requests behave as expected, and Windows proxy settings can be restored after exit. Once these checks pass, add automatic subscription updates, custom routing, or TUN one at a time to make any new issues easier to pinpoint.