Desktop uses Avalonia to provide a cross-platform interface, while WPF is a Windows desktop UI framework. On macOS or Linux, choose the Desktop package for your platform. Windows users can decide based on their current setup, workflow, and feature needs. This guide covers how to identify each build, where the interface ends and the core begins, how to migrate settings, and what to test after switching—so you don’t mistake UI differences for differences in protocol support or network speed.
Where Desktop and WPF differ
Avalonia and WPF are UI frameworks, not proxy protocols or network-processing cores. In v2rayN, the server list, subscription groups, and settings window belong to the client interface. Whether a connection succeeds also depends on the core in use, server parameters, routing rules, and network conditions. A working interface does not mean the core has started successfully.
| Category | Desktop（Avalonia） | WPF |
|---|---|---|
| Target platforms | For Windows, macOS, and Linux; download the package for your operating system | For Windows only; not a native app for other operating systems |
| Interface | Cross-platform controls and layouts, with platform-specific integration | Windows desktop controls and interaction patterns |
| Protocol support | Depends on the core in use and the configurations it supports | Also depends on the core in use and the configurations it supports |
| Using the app | Check tray behavior, keyboard shortcuts, window scaling, and permissions | Fits established Windows workflows |
| Configuration migration | Check the target release’s configuration format and where its features are accessed | Never assume configurations can be copied directly between any two versions |
Even when both versions use the Xray core, window appearance alone cannot tell you whether VLESS, VMess, or REALITY will work. Check the actual core version and the fields required by your server. Nor does “cross-platform” mean faster, or “Windows-only” mean lower latency. A meaningful speed comparison requires the same server, core, routing, and test conditions.
Bottom line: choose your platform, then verify features
Before downloading, rule out packages that don’t support your platform. After installation, use the same server to test subscription updates, proxy routing, and core logs. Don’t switch UI frameworks just to fix a server handshake failure.
Choosing a version on Windows
Windows is supported by both interface options. If you’re installing for the first time, Desktop is a good starting point. If you already have a stable WPF workflow, there’s no need to migrate just for a different interface. These recommendations are for first-time installations; neither option is guaranteed to be faster or more feature-rich on every device.
Desktop（Avalonia）
RecommendationA good starting point for a fresh install, especially if you also use v2rayN on macOS or Linux. Core concepts are similar, but verify tray behavior and system proxy integration on each platform.
Best for: New Windows installs and users switching between desktop operating systems
WPF
If your current setup works well, you can keep using it. If you rely on specific shortcuts, list interactions, or window layouts, note those requirements and check whether the Desktop build meets them before migrating. There’s no need to switch first and look for replacement controls later.
Best for: Stable existing setups and users who rely on familiar Windows interactions
System architecture and runtime requirements
- Open Windows Settings → System → About and check System type. Choose the matching x64 or ARM64 build; “64-bit” does not necessarily mean x64.
- On the client download page, check the Windows package’s interface type, architecture, and runtime requirements. Follow the release notes to see whether you need to install a runtime separately.
- After launch, check the main window, tray icon, and exit behavior. If the window won’t start, check the runtime and architecture first. If it opens but the proxy doesn’t work, check the core logs.
The UI and core run as separate processes. An incompatible package can fail before the window opens. A missing core file, occupied port, or incompatible configuration field may not become apparent until you select a server. Track these as separate stages to troubleshoot more directly than by repeatedly reinstalling over the existing setup.
Choosing a package for macOS or Linux
On these platforms, choose the Desktop package for your operating system. Don’t copy the Windows WPF package over and then assume a subscription is broken when it won’t start. Operating system, CPU architecture, and package format are separate requirements—check each one.
Platform setup: identify the architecture, then check system integration
macOS
- Open the Apple menu → About This Mac and check Chip or Processor.
- Choose the ARM64 package for Apple Silicon and the x64 package for Intel Macs.
- After launch, check the tray menu, system proxy, and whether proxy settings are restored on exit.
- For TUN, follow the current release’s permission prompts. TUN is not the same as a standard system proxy toggle.
Linux
- Run
uname -min a terminal to check the machine architecture. x86_64corresponds to x64;aarch64usually corresponds to ARM64.- Choose a package format supported by your distribution, such as deb, rpm, or another available format.
- Check whether your desktop environment supports a tray icon and proxy settings, and verify the permissions required for TUN.
Desktop does not provide identical system integration on every platform. First check whether your everyday apps can use the proxy, then configure TUN if needed.
On Linux, desktop system proxy settings typically depend on support from the desktop environment and individual apps. A browser may use these settings, while terminal programs may need proxy parameters configured separately. TUN involves a virtual network interface and routing changes, with different permission and implementation requirements. If terminal traffic isn’t routed through the proxy, that doesn’t mean Desktop can’t connect to servers.
Check feature support by task
The interface name is no substitute for a feature checklist. Verify subscription imports, group management, routing, core selection, system proxy, and TUN separately. Menus and feature availability can vary by release. The menu names below are pointers; check your installed version for the exact locations.
| Task | Menu or setting | What to verify |
|---|---|---|
| Update subscriptions | Subscription Groups → Subscription Group Settings; run Update subscription | The existing subscription URL updates, and groups and filtering behave as expected |
| Local listener | Settings → Parameter Settings; check the local listening address and port | Core logs show no address-in-use errors, and apps connect to the actual listening port |
| System proxy | System Proxy menu in the main window or tray | The system proxy points to the client’s actual port and returns to the expected state when disabled |
| Routing | Settings → Routing Settings; check rule order and outbound tags | Destinations that should bypass or use the proxy match the expected rules |
| Core compatibility | Core selection and startup logs | The core in use accepts the required protocols, transport, and security parameters |
| TUN routing | TUN toggle, permission prompts, and related logs | Routing works when enabled, and network access recovers when disabled |
For example, if your existing setup connects apps to 127.0.0.1:10808, check after migration that the new instance still listens on that port and confirm which proxy protocol it provides. 10808 is an example to check, not a default shared by every release. Don’t point an HTTP proxy at a port that only provides SOCKS; check the current settings to see whether mixed-protocol listening is supported.
- Interface issue: If buttons, list column widths, keyboard shortcuts, or scaling behave unexpectedly, note the UI version, operating system, and display scaling factor.
- Core issue: If logs report an unrecognized field or protocol, check the selected core and configuration rather than just resetting the window layout.
- Traffic routing issue: If the core is running but apps aren’t using the proxy, check the system proxy, each app’s proxy settings, and TUN before deleting subscriptions.
Migrate settings and keep a rollback option
The goal is to reuse subscriptions and rules, not to overwrite the new package with the entire old directory. Versions may change their database or configuration format. Even if the new app reads the configuration successfully, the old app may no longer be able to read the modified files. Keeping a separate backup is safer than sharing a configuration directory.
- Record your current setup. Note the client version, core type, local listening port, routing mode, and subscription groups. Subscription URLs are sensitive; don’t include them in public screenshots.
- Exit the old instance and make a backup. Turn off the system proxy, disable TUN, and exit the client. Use the backup or export feature provided by your current version. If you need to copy the configuration directory, do so after the app has exited.
- Install the other interface separately. Use a separate application directory and isolate its configuration using a method supported by the release. Don’t assume data is isolated just because the apps are in different directories.
- Restore settings in stages. Import the subscription first and test a known-good server. Then migrate custom routing, DNS, and other settings. Don’t import every change at once and then guess what caused a problem.
- Check ports and traffic routing. Make sure the old core has exited and the new instance has no port conflicts. Test an explicitly configured proxy first, then enable the system proxy, and test TUN last.
- Keep a rollback option. If a key feature is missing, exit the new instance and restore the separate backup. Don’t let the old app read configuration files modified by the new version unless compatibility has been confirmed.
When testing as a regular user, change only the interface first. If you also change the server, core, DNS, and routing, you won’t know which change affected the result. Before sharing logs, remove subscription URLs, user identifiers, and server credentials.
Common questions about choosing a version
If WPF already works on Windows, do I need to switch to Desktop?
Not just for the name. List your actual needs first, such as using v2rayN across desktop operating systems, display scaling, or access to a specific control. Then test Desktop with a separate configuration. If your subscriptions, routing, and system proxy are all working reliably, you can stick with your current setup.
Desktop opens, so why can’t it connect to a server?
Check the core startup logs for port conflicts, missing files, or configuration parsing errors. Then verify the server address, port, transport, and security parameters. An open window only confirms that the UI process started; it doesn’t confirm that the core established a connection.
Will switching to Avalonia make VLESS or VMess faster?
There’s no general speed gain from changing the UI framework alone. Test with the same server, core, and routing, and make sure background subscription updates or a second proxy process aren’t affecting the results. If these conditions differ, you can’t attribute the outcome to Avalonia.
What if I can’t find the same menus on macOS or Linux as on Windows?
First confirm that you downloaded the Desktop package for your platform. Then look for the Subscription, Routing, System Proxy, and TUN features in the main window, settings, or tray menu. If the current release doesn’t provide a particular control, check its documentation instead of copying configuration paths from another operating system.
Can I overwrite the entire directory if importing the old configuration fails?
Stop the overwrite and keep your backup. Try importing only the subscription, then restore rules one at a time after confirming that a basic connection works. For a full migration, first check that the source and target versions support the same format. Use the separate pre-migration backup if you need to roll back.