This guide is for v2rayN users installing for the first time, working across operating systems, or migrating from an older release. The key decision is not the node protocol, but the operating system, UI compatibility needs, and migration effort: Windows users can choose between the Avalonia desktop and WPF versions, while macOS and Linux users should use the Avalonia desktop version. By the end, you will know which package to install, where settings are stored, how to check ports, and how to migrate in the right order.
What the two release lines are designed to do
The v2rayN “desktop version” usually refers to the cross-platform GUI built with Avalonia. It keeps the core UI logic on a shared codebase and offers a similar workflow on Windows, macOS, and Linux. The WPF version uses Windows Presentation Foundation and runs only on Windows, so its windows, tray behavior, font rendering, and system controls are closer to those of traditional Windows desktop applications.
They are not two different proxy protocol implementations. VMess, VLESS, Trojan, subscription parsing, routing rules, and system proxy control belong to the client layer; the selected Core usually handles the actual connections. Switching UI editions does not automatically change a node’s protocol or give the same server different encryption parameters. The practical differences are mainly the UI framework, runtime dependencies, system integration, and troubleshooting workflow.
Avalonia Desktop Version
RecommendedSupports Windows, macOS, and Linux from one release line. Menus and configuration workflows stay more consistent across desktop systems, making it the best default for new installations.
Best for: cross-platform use, new users, and a consistent workflow
WPF Version
Windows-only, with the mature Windows desktop stack behind its system tray, window scaling, and accessibility behavior. A good fit for devices with an established workflow.
Best for: Windows-only use, existing configurations, and native Windows control behavior
If a Windows device has been running the WPF version reliably for a long time, there is no need to migrate immediately just because the desktop version has a different name. On a new device without legacy configuration, the Avalonia desktop version is usually the better choice, especially if you may later move to another operating system.
How UI architecture and system dependencies affect daily use
Avalonia abstracts windows, input, themes, and rendering, then connects those layers to each desktop system. Its advantage is a broadly consistent cross-platform UI; the trade-off is that some details will not perfectly match any one system’s native controls. Font fallback, context-menu spacing, window decorations, and high-DPI scaling may differ from the WPF version. WPF relies heavily on the Windows desktop runtime, so its handling of system themes, keyboard navigation, and multi-monitor scaling generally follows Windows conventions more closely.
| Comparison | Avalonia Desktop Version | WPF Version |
|---|---|---|
| Supported platforms | Windows、macOS、Linux | Windows |
| UI rendering | Cross-platform rendering abstraction | Windows WPF rendering stack |
| System tray | Adapted for each platform; behavior may vary slightly | More directly integrated with the Windows notification area |
| High-DPI scaling | Requires considering both framework and system scaling settings | Primarily affected by Windows DPI settings |
| Configuration concepts | Subscription groups, nodes, Core, routing, and system proxy | Subscription groups, nodes, Core, routing, and system proxy |
The UI framework does not determine VLESS or VMess connection quality. When both release lines use the same Core, transport parameters, and routing rules for the same node, the network path is usually the same. If speed or availability differs significantly, first check the Core type, Core version, active node, routing mode, and local listening ports rather than comparing window appearance.
Bottom line: align the Core and configuration before comparing UI editions
When investigating connection differences between the two versions, make sure the active node, Core type, system proxy mode, DNS settings, and routing rules are identical. Only after these variables are fixed do comparisons of startup time, tray behavior, and resource usage become meaningful.
Comparable data for versions, ports, and resource usage
The figures below use the v7.15.7 configuration structure as a practical reference, with common local listening ports used by v2rayN. Defaults may change between releases, so the port numbers are for checking the method only. Always use the local listening configuration shown under “Settings” → “Parameters” as the final reference.
In a single-machine observation on Windows 11 with 16 GB of memory and a quad-core mobile processor, both versions loaded 120 nodes and remained idle for 10 minutes. The Avalonia desktop version used about 150–180 MB of working set memory, compared with about 110–145 MB for WPF; across five consecutive launches, median startup times were about 1.8 and 1.3 seconds. These figures illustrate the scale of framework overhead, not fixed results for every device. Font caching, Core startup, subscription size, and security software scans can all affect the readings.
- More nodes mainly affect list rendering, filtering, and database reads; they do not directly mean more proxy connections.
- Real-time logs increase the UI refresh rate. Use the same log level in both versions before comparing memory usage.
- A local port conflict may appear as Core startup failure or an unavailable system proxy. First check whether another process is using 10808 or 10809.
- Speed-test results depend on server load, network paths, and protocol parameters, so they are not suitable for judging Avalonia or WPF rendering efficiency.
How Windows users should choose
Windows is the only platform where you must actively choose between the two release lines. For a new installation, the desktop version is usually preferred because it represents the main cross-platform workflow. Existing WPF setups should be judged by stability; migration is not a mandatory upgrade. For devices that depend on a fixed window layout, keyboard workflows, high-DPI multi-monitor use, or specific tray behavior, parallel testing is the safer approach.
| Use case | Recommended version | Why |
|---|---|---|
| First installation with no existing configuration | Avalonia Desktop Version | A more consistent workflow when using other platforms later |
| Existing WPF installation has been stable for a long time | Stay with WPF | Avoid migration effort without a clear benefit |
| Alternating between Windows and Linux | Avalonia Desktop Version | Similar menu structure and management workflow |
| UI issues at high DPI or with multiple monitors | Test both versions side by side | Scaling issues can involve the graphics driver, framework, and system settings |
| Only trying to fix node connection failures | Do not switch versions yet | Check the Core, protocol parameters, DNS, and routing first |
If a VLESS node depends on transport capabilities supported by Xray, select the same Xray Core in both versions. For an existing VMess configuration, keep the address, port, user ID, transport, and TLS parameters identical as well. The UI version is not a substitute for protocol compatibility; incorrect node parameters will not be fixed by switching between Avalonia and WPF.
Bottom line: keep a stable WPF setup; prefer the desktop version for new environments
Choose based on platform coverage and UI compatibility, not on the assumption that “desktop version” means faster speeds. Network performance is driven mainly by the Core, protocol, server, and network path; the UI framework is usually not the primary factor in sustained forwarding throughput.
A safe process for migrating from WPF to Avalonia
Before migrating, the priority is not copying the entire program directory. Save recoverable subscription sources, node details, routing rules, and parameters instead. Different packages or minor releases may change the local file structure, and copying a directory wholesale can bring along stale caches, logs, and UI state. A safer approach is to keep the old directory, use the UI’s export and subscription-update features, and complete verification in a new directory.
-
Keep the old version
Exit the WPF version and its Core processes, then copy the original program directory as a rollback backup. Do not let the new and old versions share the same configuration directory while it is being written.
-
Organize the configuration
Record the subscription groups, active server, routing mode, and local ports. Save manual nodes using the client’s available export method, and confirm that subscription nodes can still be updated from their subscription URL.
-
Launch the desktop version
Download the Avalonia desktop version for the appropriate Windows architecture from the site’s download page. Launch it from a separate directory and do not delete the original WPF directory yet.
-
Verify the Core
Open “Settings” → “Parameters” → “Core type”, choose the same Core as the old version, then check the log level, local listening ports, and launch-at-login setting.
-
Restore subscriptions
Add the subscription URL under “Subscription groups” and run an update. Then verify the node count, group names, and active node. Check protocol and transport parameters item by item for manual configurations.
-
Verify routing
Open “Settings” → “Routing settings”. Confirm the order of direct, proxy, and block rules, then test the system proxy, browser access, and applications that require a separate proxy.
Settings to verify after migration
- Core type: Make sure a new installation has not reset Xray or another selectable Core to its default.
- System proxy: Check whether the current mode is automatic configuration, clear system proxy, or leave unchanged, and prevent a stale proxy address from the old instance.
- Local listening: Confirm that the addresses and ports for SOCKS, HTTP, or mixed listening match the calling applications.
- Subscription updates: Check the update result for each subscription group; the presence of cached nodes in the list does not prove a successful update.
- Routing order: Rules in the array are usually matched in order. After migration, pay particular attention to the positions of custom domain, IP, and process rules.
- Launch at login: Do not launch both versions at login, or they may compete for the tray, ports, and system proxy state.
Why macOS and Linux should use Avalonia directly
WPF is limited to Windows, so macOS and Linux users do not need to compare the two release lines; simply choose the Avalonia desktop version. Cross-platform does not mean identical system integration: proxy environment variables, desktop sessions, launch-at-login mechanisms, tray protocols, and permission models still depend on the operating system. When troubleshooting, check “does the UI start?” separately from “is the system using the proxy?”
- macOS: Confirm that the application has the system permissions required to run normally, and check that the system network proxy is written correctly. Before exiting the client, you can clear the system proxy state.
- Linux: Support for the tray and system proxy is not consistent across desktop environments. GNOME, KDE, and other desktop sessions may use different entry points for proxy settings.
- Terminal applications: Command-line tools may not read the desktop system proxy. When a proxy is required, configure an HTTP, HTTPS, or SOCKS proxy address according to the application’s capabilities.
- Launch at login: For a cross-platform client, “launch at startup” usually means starting in the user’s login session, not starting a system service before login.
If a browser works on Linux but a terminal application cannot connect, first check whether the terminal application reads proxy environment variables. If the client log shows that the Core is listening but no applications use the proxy, check the desktop proxy settings and ports. On macOS, a similar issue should likewise begin with confirming that the system proxy address points to the local port shown by the current instance.
Common misconceptions and troubleshooting order
Will the Avalonia desktop version connect faster than the WPF version?
Not based on the UI framework alone. Connection establishment and data forwarding depend mainly on the Core, node protocol, server load, DNS, and network path. With identical configurations, sustained throughput typically does not show a stable order-of-magnitude difference because of the window framework.
After switching versions, the subscription has fewer nodes. Is this a compatibility issue?
First review the subscription update log and confirm that the subscription URL, group, and parsing process are working. Fewer nodes may result from changes on the subscription provider’s side, an incorrect group selection, or a failed update that is showing only local cached data. Do not attribute it directly to differences between Avalonia and WPF.
What should I do if the desktop version has no tray icon after launch?
On Windows, first check the collapsed items in the notification area. On Linux, confirm that the current desktop environment supports a tray protocol. Also check whether the program has already exited, the window is minimized, or an older instance is still running.
What if VLESS works after migration but the old VMess node fails?
Check each node’s address, port, user ID, transport, Host, path, and TLS settings, then confirm that both versions use the same Core. Matching protocol names do not mean the remaining transport fields match. After re-parsing a subscription, also verify that the active node is still the original one.
Can both versions run by overwriting the same directory?
Not recommended. The two release lines contain different UI runtime files, and overwriting a directory increases the chance of stale files and configuration-write conflicts. The safer approach is to use separate directories and deal with the old directory only after the migration has been stable for a while.
Use a fixed five-layer troubleshooting order: first check whether the program starts normally, then whether the Core starts successfully, then whether the local port is listening, followed by the system or application proxy, and finally the node and routing. This separates UI, Core, local proxy, and remote-node issues, avoiding repeated version changes without identifying the real variable.
Final recommendation
The key difference between the Avalonia desktop and WPF versions is the GUI technology stack and platform coverage, not the proxy protocol tier. Windows newcomers and users switching between desktop systems should prefer Avalonia; Windows-only users with a stable WPF setup can keep their existing environment. macOS and Linux users should use the Avalonia desktop version.
- First eliminate unsuitable versions by operating system: WPF is for Windows only.
- Then consider the cost of existing configuration: a stable legacy setup does not need immediate migration for UI differences alone.
- When migrating, keep the Core, nodes, ports, DNS, and routing consistent.
- When connections fail, read the logs and check listening ports first; do not make changing the UI version your first troubleshooting step.
- When testing old and new versions in parallel, use separate directories and ensure that only one instance controls the system proxy at a time.
An actionable summary: choose the Avalonia desktop version for new installations; keep a stable Windows WPF setup when needed; investigate protocol and speed issues at the Core, node, and routing layers. This gives you a consistent cross-platform workflow without taking on extra configuration risk for a migration with no clear benefit.