Choose by operating system first, then by the way you work: use the Avalonia desktop edition on macOS and Linux; on Windows, compare Avalonia and WPF. The main differences are the UI framework, desktop integration, and runtime requirements—not the proxy protocol or speed. This guide covers a side-by-side comparison, installation checks, and migration steps for desktop users choosing a version or planning to switch.
Know the difference between the UI framework and proxy core
Avalonia and WPF are both technologies for building graphical user interfaces. They determine how windows, lists, menus, and input controls look and behave. v2rayN uses these interfaces to manage servers, subscription groups, routing rules, and proxy controls; the selected core handles the actual proxy connection. Choosing Avalonia does not mean switching to a particular protocol, and choosing WPF does not limit you to a particular core.
If a VLESS or VMess node will not connect, check its settings, core support, and logs first. Don't judge the cause by the window's appearance. Even when two copies show the same subscription name, different core versions, active nodes, or routing settings can produce different results. Align these variables before comparing UI editions.
| Layer | Responsibilities | Where to troubleshoot |
|---|---|---|
| Avalonia / WPF | Window display, menu interactions, desktop integration | UI settings, system display settings |
| Proxy core | Protocol handling, connection setup, rule execution | Core selection, runtime logs |
| Nodes and subscriptions | Server address, port, authentication, and transport settings | Server editor, subscription group settings |
Choose Avalonia or WPF by platform
The Avalonia desktop edition supports Windows, macOS, and Linux; WPF is a Windows-only UI option. “Cross-platform” means builds are available for the respective systems—not that one installer runs on all three. Before downloading, check your processor architecture, such as x64 or ARM64, as well as the edition name.
Avalonia desktop edition
RecommendedA good starting point, especially if you want a similar workflow across multiple desktop operating systems. Check the system version, architecture, and desktop environment requirements for your device.
Best for: macOS and Linux users, and Windows users who want a consistent desktop workflow.
WPF edition
Keeps the familiar Windows UI workflow. If your setup is stable and you're used to its menus and tray behavior, you can keep using it while evaluating the newer interface separately.
Best for: Windows users who prefer their existing UI workflow.
The Recommended label reflects the selection order in this guide; it does not mean the WPF edition is no longer maintained. Windows users don't need to switch just to get “cross-platform” support. If your current setup is stable, verify functionality and compatibility before following a UI change.
Compare the interface, tray, and window behavior
Both interfaces organize tasks around server lists, subscription groups, logs, and settings, but menu locations, saved column widths, keyboard shortcuts, and right-click options may change between versions. On first launch, locate the active server indicator, system proxy status, and logs before adjusting the theme, font, or list columns. Don't rely on screenshots of another edition to click by position.
| What to check | Avalonia desktop edition | WPF edition |
|---|---|---|
| Window and scaling | Check scaling, fonts, and control layout on your current system | Check Windows scaling and behavior when moving between monitors |
| System tray | Depends on system support and the Linux desktop environment | Check the Windows notification area and hidden icons |
| Close button | Check whether the app keeps running in the background after the window closes | Check close behavior and the tray menu's exit option |
| System proxy | Verify that the setting is applied in the current desktop session | Verify Windows proxy settings and the client status |
Closing a window doesn't necessarily exit the app. To test the tray, close the main window and try reopening it from the tray. To stop the app, choose Exit from the tray menu and confirm that the proxy settings have been restored. If the window disappears but the connection is still active, check for a background process before launching another copy.
- Windows: Open the taskbar's hidden icons area and make sure the tray icon isn't tucked away. After moving the window to another monitor, check its scaling and position.
- macOS: Know the difference between closing a window and quitting the app. Check the menu bar entry and test the connection after waking the Mac from sleep.
- Linux: Check whether your desktop environment supports a system tray or status indicator. A missing tray icon alone doesn't mean the proxy core failed to start.
Check runtime requirements before installing
If the app won't open when you double-click it, check the package type, architecture, and runtime requirements before changing nodes. The WPF edition typically requires the corresponding .NET Desktop Runtime. Avalonia's requirements depend on whether the release package is self-contained and which native libraries the system needs. A self-contained package includes the relevant managed runtime, but still has operating system requirements.
- Check your operating system and architecture. On Windows, go to Settings → System → About to check the system type; on macOS, check About This Mac for the chip; on Linux, look in the system settings' About page for the OS and processor details.
- Read the package details. Distinguish the desktop edition from WPF, and check whether the package is self-contained, its minimum system requirements, and its architecture. Don't keep trying to unpack a package built for another operating system.
- Install dependencies based on the error. If the startup dialog names a missing framework, version, or architecture, install the one specified. The Desktop Runtime required by WPF is not the same as the standard .NET Runtime.
- Keep the full application folder. Extract portable packages in full to a writable location; don't copy only the main executable. Check the release's folder layout for the actual locations of core files, resources, and configuration.
Switch editions: back up first, then test separately
Whether you're moving from WPF to Avalonia or back again, don't overwrite the program folder you're currently using. Configuration formats and data locations may differ between versions. To reduce risk, keep the existing setup, install the new edition in a separate location, and migrate using the client's backup, restore, or import feature. The exact menu may vary by version.
Migration plan: keep the old setup and test the new UI separately
Old setup: keep it for rollback
- Note the client version, core, and active node.
- Back up subscription groups, routing, and custom settings.
- Exit the app before backing up its actual data directory.
New setup: verify each item
- Import one subscription group first and check the node count.
- Test with the system proxy first; leave TUN off.
- After confirming the connection, restore custom routing.
Don't let both copies manage the system proxy or use the same listening port. Decide which one to keep only after testing is complete.
For example, if the old setup listens on 127.0.0.1:10808 and the new one binds to the same address and port, it may fail to start. Exit the old setup completely before launching the new one. If you need to test both at once, assign the new setup a different port and update the test app's proxy settings. The 10808 port in this article is only an example, not a fixed default for every version.
- Check the local listening settings under Settings → Parameter Settings. Names and sections may vary by version, so use the options shown in your app.
- Select the same node and core as in the old setup, then make sure the system proxy points to the new setup's actual listening port.
- Visit the same test site and check the logs for port binding, handshake, or DNS errors. Change one setting at a time.
- Test subscription updates, reopening from the tray, proxy restoration on exit, and startup behavior after a restart. Then migrate the remaining groups.
A subscription restores only the node information it contains; it won't restore all local settings. Check manually added servers, routing rules, DNS settings, and shortcuts separately. Backups may contain subscription URLs and authentication details, so store them securely and don't post them publicly as support attachments.
FAQs and final recommendations
Why won't the same subscription connect after switching editions?
First check that the active node is the same, then compare the core type and version, routing, and system proxy settings. Check the logs for a local port conflict; if the old app is still running in the background, exit it. Matching subscriptions don't guarantee matching runtime settings.
Which edition should I install first on Windows?
If you're new to v2rayN, start by testing the Avalonia desktop edition. Choose WPF if you prefer the familiar Windows workflow or find that specific window behavior is more stable in your setup. After installation, check tray behavior, proxy settings, and restart behavior—not just whether the window opens.
Will switching to WPF make a VLESS node faster?
You can't assume that. Match the node, core, and routing, then test at similar times. If only list scrolling is sluggish, check display scaling, list size, and UI settings. If websites load slowly, investigate the network and logs.
Can I keep using the new UI without a tray icon?
First confirm that the main window works and check whether the system has hidden the icon. On Linux, also check for system tray support in your desktop environment. Test whether you can reopen the app after closing its window. Until you know how to restore it, keep the window open rather than relying on unverified background behavior.
Can I put the new and old versions in the same folder?
For migration testing, use separate folders and check whether both versions still point to the same data location. Don't let two copies write to the same configuration store. Keep the old setup recoverable and clean it up only after the new one is stable.
Make your choice based on three factors: whether it runs on your system, whether it has the features you need, and whether its desktop behavior suits your workflow. Start with the Avalonia desktop edition on macOS and Linux; on Windows, choose the UI you've tested on your device. If connections fail, troubleshoot the UI, core, and node separately before deciding whether to switch editions.