For a first-time install, choose a package for your operating system and processor architecture, then pick the Avalonia or WPF edition. On Windows, base your choice on your existing setup and workflow. On macOS or Linux, use the desktop package for that operating system. These are two UI frameworks, not two proxy protocols, and the interface alone does not determine connection speed. This guide covers package selection, runtime checks, settings to compare, and a separate-directory migration process.
UI frameworks, clients, and proxy cores
Avalonia and WPF are both UI frameworks. The client interface handles server lists, subscription groups, settings, and tray menus; the proxy core that the client invokes handles connections, protocol processing, and traffic forwarding. Confusing a UI change with a protocol change can send troubleshooting in the wrong direction.
WPF is a Windows desktop UI framework, so the WPF edition of v2rayN is for Windows. Avalonia supports cross-platform interfaces, allowing v2rayN to offer builds for different operating systems. Cross-platform means the same UI technology can be used to build for multiple systems—not that one Windows executable runs on every operating system.
- v2rayN: Stores server details, manages subscriptions, generates runtime configuration, and invokes the appropriate proxy core.
- Xray and V2Ray: Proxy cores. The available cores and features depend on the version installed and the files included in the package.
- VMess and VLESS: Protocols. Whether a node works also depends on its transport, security settings, and server parameters.
- Avalonia and WPF: UI technologies. They are not substitutes for protocol or proxy core names.
Troubleshoot in order: check the core before comparing interfaces
If the same VLESS node behaves differently in the two editions, first align the core version, node parameters, routing, and DNS settings. Then check whether a setting was not saved or whether the option is in a different place. Don’t infer protocol compatibility from the look of the window.
Avalonia vs. WPF at a glance
The most useful differences when choosing a version are its target operating system, where features are found, and its runtime environment. Use the table to narrow down your options; it does not mean both editions have identical features in every release. New features, option names, and layouts may vary between versions.
| Comparison | Avalonia desktop edition | WPF edition |
|---|---|---|
| Supported operating systems | Choose a release package for Windows, macOS, or Linux | Windows |
| Processor architecture | Choose an available package that matches the target OS, such as x64 or ARM64 | Match the Windows device to an architecture offered by the release package |
| Everyday use | Subscriptions, servers, and settings are presented in a cross-platform interface | Subscriptions, servers, and settings are presented in a Windows interface |
| Proxy capabilities | Depend on the proxy core, version, and configuration in use | Likewise depend on the proxy core, version, and configuration in use |
| Runtime requirements | Depend on whether the package includes a runtime and on native OS dependencies | Depend on whether the package includes a runtime; framework-dependent packages require the .NET Desktop Runtime |
| System integration | Tray, system proxy, and permission behavior varies by operating system | Uses Windows tray, system proxy, and permission mechanisms |
Without tests under controlled conditions, don’t assume one interface edition always uses less memory or runs faster. Memory use also depends on the number of nodes, log display, proxy core activity, and whether the window is open. Download speeds are usually more affected by the network route, server load, and routing rules.
Choose a version based on your OS and current setup
First choose a package that runs on your system, then choose the interface you prefer. For a fresh Windows install, if the download page offers an Avalonia desktop package for your architecture, it can be a good place to start. If your WPF setup is already working well, there’s no need to switch working directories just to change UI frameworks.
Avalonia desktop edition
RecommendedA good starting point for a fresh install. On macOS or Linux, choose the package for your operating system; Windows users can also choose a compatible desktop package. Check tray, proxy, and permission settings separately on each system.
Best for: First-time setup, use across operating systems, or users who want a similar workflow on different devices.
WPF edition
A good fit if you want to keep your existing Windows workflow. If your subscriptions, routing, and system proxy already work, you can keep using WPF and switch only if you need a feature available in another version.
Best for: Windows users familiar with the WPF interface who already have a stable configuration.
- Check your operating system: In Windows, go to Settings → System → About to view your device specifications. On macOS, check the chip information under About This Mac.
- Check your architecture: Identify whether you need x64 or ARM64. Don’t rely on the computer brand alone, and don’t confuse OS bitness with processor architecture.
- Read the package details: Check the target OS, architecture, included runtime, and minimum system requirements.
- Check for required features: If you need TUN, custom routing, or a specific proxy core, make sure the version includes the relevant option and runtime components.
Runtime requirements and first-launch checks
Having “.NET installed” does not necessarily mean you have the runtime the app needs. Runtimes differ by version, architecture, and type. WPF apps need desktop support, so the standard .NET Runtime alone may not be enough. The SDK is intended for development and should not be the default fix for a first-launch problem.
Runtime checks: two paths depending on how the package is distributed
Packages that include a runtime
- Extract the entire package, then launch the app from the extracted folder.
- Don’t copy only the main executable and leave its neighboring dependency files behind.
- If the app won’t start, check system requirements, execution permissions, and security software logs.
Packages that require a system runtime
- Note the runtime name and major version requested in the error message.
- Make sure the runtime architecture matches the application package.
- For a WPF package, install the required .NET Desktop Runtime, then restart the app.
Bottom line: Install the dependencies listed for the package. Don’t troubleshoot by installing several unknown runtime versions one after another.
On Windows, run the command below in a terminal to see which .NET runtimes are installed. If the command isn’t recognized, check the package details to see whether a system runtime is required. For packages that include a runtime, this command alone cannot tell you whether the app will launch.
dotnet --list-runtimesWhen reviewing the results, distinguish Microsoft.WindowsDesktop.App from Microsoft.NETCore.App, and compare the versions with the error message. Avalonia packages for macOS or Linux may also depend on system graphics libraries or execution permissions, so don’t apply Windows runtime fixes directly. Track a window that won’t open separately from a proxy core connection failure; the latter usually requires checking the client logs.
Check subscriptions, system proxy, and listening ports in order
Both interfaces can show the same server list without having the same connection setup. Check “Subscription groups” → “Subscription group settings,” the active server, “Settings” → “Parameter settings,” and “Routing settings,” in that order. Button locations and option names may vary by version, so use the current interface as your guide.
Ports are an easy-to-miss detail when migrating. This guide uses 127.0.0.1:10808 as an example local proxy address and 10818 as an alternative to try if there’s a conflict. These values illustrate what to check; they aren’t default ports for every version.
- Subscriptions: Open “Subscription groups” → “Subscription group settings” to check the URL, then select “Update all subscriptions.” Subscription URLs contain access credentials; don’t include them in public screenshots.
- Listening ports: Go to “Settings” → “Parameter settings” and look for local listener options. In some versions, these are under “Core Basic Settings.” Check whether the field is for a mixed port or separate SOCKS and HTTP ports before configuring an app to use the proxy.
- System proxy: In Windows, check the “System proxy” menu in the main window or system tray. Selecting a node does not automatically turn on the system proxy.
- Routing: Check the rules and their order under “Routing settings.” With “Bypass mainland China (Whitelist)” enabled, some requests are expected to connect directly; that alone doesn’t mean the proxy has failed.
- DNS and TUN: Record the DNS policy and TUN status separately. TUN requires a compatible proxy core, OS support, and permissions; it is not a universal setting automatically carried over when you switch interfaces.
Migration check: run only one client instance at a time
Exit the old version and make sure its proxy core has stopped before starting the new one. If the logs still show a port conflict, identify the process using the port. Only assign different ports when you’ve confirmed that you need both versions running at once; otherwise, the two interfaces could both change the system proxy.
Move from WPF to Avalonia using separate directories
Don’t switch interfaces by overwriting the old directory. Data structures, setting fields, and migration behavior can vary between versions, and copying the entire directory may mix an old proxy core with new files. Keep a restorable copy first, then test the new setup—it’s easier than trying to recover the old configuration after something goes wrong.
- Document the old setup: Note the client version, proxy core, active subscription group, listening ports, routing profile, and system proxy status. Record custom DNS or TUN settings too.
- Back up your data: Use the export or backup feature provided by your current version. If there’s no clear option, exit the app and back up its configuration data directory. Store the backup somewhere secure; it may contain node credentials.
- Set up a new directory: Extract the new package to its own directory. Don’t overwrite the old one or let both apps write to the same configuration.
- Re-create subscriptions first: Add a subscription group in the new interface and update it. Subscriptions usually provide node details only; they don’t automatically restore local routing, listening ports, DNS, or system proxy preferences.
- Restore settings one at a time: Test a single node first, then restore routing and DNS, and enable TUN only if needed. Verify the setup after each category of changes to make it easier to find problems.
- Keep a rollback path: If the new version has problems, turn off its system proxy and exit before returning to the old version. Don’t leave the system proxy pointing to a port that is no longer listening.
When moving between operating systems, recreate local settings from scratch. Windows paths, startup behavior, certificate locations, and permissions don’t carry over directly to macOS or Linux. Successfully importing a subscription only confirms that its node data was readable; it doesn’t prove the local proxy is fully configured.
Version selection and migration FAQs
WPF works on Windows. Do I still need to switch?
There’s no need to switch just because the framework name is different. List the features you’re missing, then check the target version’s release notes. If you want to try it, install it in a separate directory, keep the old configuration, and compare both versions using the same node and routing rules.
Will my existing VMess or VLESS subscription work in the desktop edition?
Add the existing URL under “Subscription groups” → “Subscription group settings” and update it. Whether it can be parsed and connected depends on the subscription format, node parameters, and proxy core support. If there’s an error, check the update log rather than assuming it’s due to the interface edition.
The node appears in the list. Why won’t my browser load pages?
First check the active server and proxy core logs, then check the “System proxy” status. If the browser has a manually configured proxy, make sure its address and port match the current listener. If you switch to port 10818, apps still pointing to 10808 won’t follow automatically.
What if I can’t find a button from an older tutorial in the new interface?
Look for options by name, such as “Subscription groups,” “Parameter settings,” and “Routing settings,” rather than following screenshot coordinates. Check the client version first. If the current build doesn’t include the option you need, consult the release notes for that version; don’t edit generated proxy core configuration as a substitute for a missing settings option.
Can I install both versions and run them at the same time to compare?
For an initial comparison, start one version at a time. If you must run both simultaneously, isolate their configuration directories, listening ports, and system proxy controls. Don’t let both instances manage the system proxy automatically. Align the node, routing, and DNS settings before comparing; otherwise, the results won’t be meaningful.