v2rayN Avalonia desktop version vs. WPF version: Platform Support and Which Version to Choose

Compare v2rayN Avalonia and WPF by platform support, runtime requirements, and interface. Find the right download for Windows, macOS, or Linux, and learn how to migrate your settings.

At a glance

For a first-time install, choose the Avalonia desktop version that matches your operating system and processor. If you use Windows only and prefer the classic interface, you can stick with WPF. The main differences are the interface and platform support—not the node types. Back up your data before switching, then check your subscriptions, routing rules, and local ports.

Platform support: Avalonia or WPF?

Avalonia and WPF are interface frameworks used to build windows, menus, and buttons. They are neither proxy protocols nor the core that handles connections. When comparing the same VLESS or VMess node, first make sure the core and its version, node settings, and routing rules are the same. The interface name alone doesn't determine compatibility or connection speed.

Avalonia desktop version

Recommended

Available for Windows, macOS, and Linux, with a separate installer for each platform. Using the same interface framework helps keep the experience consistent, but menus, the system tray, and system proxy behavior still vary by operating system.

Best for: First-time installs or switching between desktop operating systems.

WPF version

For Windows. If you're familiar with the classic interface and your current setup works, there's no need to reinstall just for a different look. Check the processor architecture and runtime requirements listed on the download page before choosing a package.

Best for: Windows users who want to keep the classic interface.

When following an older tutorial, first check which interface its screenshots show. A different window layout doesn't mean a feature has been removed. Look for areas such as the node list, subscription groups, and logs by name rather than expecting buttons to be in the exact same places as in the screenshots.

Installer architecture and .NET runtime requirements

Choose an installer in this order: operating system, processor architecture, package format, then whether you need to install a runtime separately. For example, with the v2rayN 7.x series, the major version number doesn't tell you that every release package requires the same .NET version or bundles its runtime. If you see a startup error, check the current package notes and the framework name, version, and architecture shown in the error.

x64
Common on 64-bit Intel or AMD computers; the equivalent Linux architecture is x86_64
ARM64
For ARM devices such as those with Apple silicon; the equivalent Linux architecture is aarch64
10808
Common local inbound ports used by v2rayN; check the actual values in settings

Back up before switching and restore settings for your migration

Switching interfaces involves more than importing nodes again. Subscription groups, manually added nodes, custom routing rules, and local listener settings are separate data. Re-fetching a subscription usually restores only the nodes provided by that subscription. Before backing up, turn off System Proxy in the old version, then quit the client from the system tray to avoid leaving it running and writing to your settings in the background.

Switching on the same computer or migrating to another system

Switching interfaces on Windows
  • Back up the data directory the old version actually uses. If guiConfigs in the program directory is in use, back up the entire directory—not just one JSON file.
  • If possible, use the same release version for both interfaces. Start the new version once on its own to confirm where it stores data, then quit it and back up that data.
  • Once you've confirmed the data formats are compatible, restore a copy of the old data. Don't let both interfaces read and write to the same data, and don't overwrite the new version's core binaries with older ones.
Switching to macOS or Linux
  • In the old version, go to Subscription Groups → Subscription Group Settings and note your subscription URLs. Export or record any manually added nodes separately.
  • Install the client for the correct architecture on the new system, then restore your subscriptions and nodes. Don't copy over Windows absolute paths, startup settings, or core program files.
  • Go to Settings → Routing Settings to check custom rules and any local files they reference. Update the paths to match the new system's directory structure.

Whichever method you use, keep the original backup. Subscription URLs and node share links may contain access credentials, so don't include them in public screenshots or logs.

After switching, check nodes, ports, and routing

First confirm that the new version has loaded your existing data, then enable its system proxy. This makes it easier to tell whether a problem is caused by missing settings, a core that won't start, or an app using the wrong proxy endpoint.

  1. Check your groups and selected node. Verify the subscription group names, manually added nodes, and currently selected node. If the list is empty, first confirm that the new version has loaded the expected data directory. Don't rush to clear subscriptions or overwrite the old version.
  2. Check the proxy endpoint and logs. Go to Settings → Parameter Settings to view the local listening ports. If the logs show address already in use, make sure the old version and its core process have exited. If you need to change a port, update any apps where you've entered a proxy address manually, and check whether they're using HTTP or SOCKS.
  3. Test routing with the same destinations. Enable the system proxy mode you need, then test one domain that should bypass the proxy and one that should use it. A page loading successfully only confirms that the request worked; check the core logs and active routing rules to see which route it took. If the issue occurs only in a terminal, check whether the terminal app uses the system proxy or has its own proxy environment variables.

Common questions about switching versions

If the WPF version works, do I need to switch to Avalonia?

Not just for a different interface. First figure out whether you need support from a newer core or a cross-platform interface. If you only need a different core, check which cores and versions your current client supports. To try the other interface, keep the original version and a backup, quit the old version, then start the new one.

The new version says .NET is missing. Can I install a newer version?

Not necessarily. Check the framework name, required version, and architecture in the error. Having a newer major version installed doesn't automatically meet the requirement. If the release page offers a self-contained package for your system, you can use it to avoid installing a separate .NET runtime for that package.

My subscriptions and nodes are there. Why isn't my browser using the proxy?

Check the logs to confirm that the core has started, then check that System Proxy in the system tray is set to the mode you need. If you configured a proxy directly in your browser, verify the port and proxy type there. Switching interfaces won't update an old address saved in the browser.

Routing is wrong after switching. How do I go back to the old version?

Turn off System Proxy in the new version and quit it, then start the old version. If you changed the old version's data directory while testing, restore the separate backup you made before migrating. Don't give the old version a database that the new version has already written to. Finally, select your original routing rules and node again, then enable System Proxy.

Download v2rayNChoose a client for your platform