Windows users can choose between WPF and Avalonia based on their preferred workflow and how each interface fits their system. macOS and Linux users should choose the desktop package for their OS. The key difference is the UI framework—not the capabilities of the proxy protocols. This guide covers runtime requirements, core components, configuration migration, and testing to help first-time downloaders and users switching versions avoid unnecessary troubleshooting.
Desktop vs. WPF: Understand the UI, Client, and Core
In this article, “desktop version” refers specifically to v2rayN’s Avalonia-based release. The WPF version is also a desktop app; the two names distinguish different UI branches on the download page. Avalonia is a cross-platform UI framework, while WPF is designed for Windows. They affect window rendering, control behavior, and desktop integration, but do not determine whether a remote server supports a particular proxy protocol.
v2rayN manages server entries, subscriptions, routing, and core processes. The selected core handles the actual proxy connection. To check whether VMess, VLESS, or a particular transport configuration will work, verify the core type and version along with the server parameters—not just whether the package uses Avalonia or WPF. The two UI versions may also differ in available features from one release to another.
| Layer | Primary role | What to check when choosing |
|---|---|---|
| Avalonia / WPF | Windows, lists, settings, and interactions | OS support, display scaling, system tray, and input behavior |
| v2rayN client | Stores configuration, manages subscriptions, and generates runtime parameters | Feature availability, configuration compatibility, and permissions |
| Xray / V2Fly core | Handles inbound and outbound traffic, routing, and connections | Protocol support, logs, and connection parameters |
Choose by Operating System: Workflow on Windows, Package on Other Systems
If you only use Windows and your current WPF version handles subscription updates, system proxy, and routing correctly, there’s no need to switch just for the words “cross-platform.” If you regularly move between Windows, macOS, and Linux, the Avalonia desktop version offers a more consistent workflow across systems, but system proxy interfaces, permissions, and tray behavior still vary by OS.
WPF: Keep Your Existing Windows Workflow
RecommendedFor users who only use Windows and are already comfortable with WPF, the default recommendation here is to keep a stable setup that works. Check that display scaling, shortcuts, and system proxy restoration meet your needs instead of assuming performance based on the UI’s name.
Best for: Windows-only users who want to keep their existing workflow.
Avalonia Desktop: Work Across Operating Systems
If you manage similar configurations across multiple desktop operating systems, choose the desktop package for your OS and processor architecture. Cross-platform means the UI framework supports multiple systems; it does not mean one installer runs on every OS.
Best for: macOS and Linux users, and anyone who regularly switches between desktop operating systems.
Android is not part of the Avalonia-versus-WPF choice. For mobile use, compare v2rayNG and v2flyNG separately: the former is built around the Xray core, while the latter uses the V2Fly core. Whether you can reuse a subscription depends on its protocols and parameters. Being part of the same V2Ray ecosystem does not guarantee every configuration can be imported as-is.
Bottom Line: Check Your OS, Then Test Your Workflow
Windows users should first test a subscription update, a proxy toggle, and proxy restoration on exit with their current version. If all three work, there’s no rush to switch. macOS and Linux users should select the Avalonia desktop package for their OS and avoid trying to run the WPF package.
Runtime and UI Compatibility: Four Checks Before Installing
Both UI versions are related to the .NET ecosystem, but that does not mean every package requires users to install the same runtime separately. Releases may be self-contained or depend on a system runtime. Check the package notes and any startup error for the exact requirements. If a runtime is missing, install the requested runtime type, major version, and processor architecture rather than an arbitrary newer release.
- Processor architecture: x64 and ARM64 packages are not interchangeable. On Windows, check Settings → System → About for your system type; on macOS, check About This Mac for your chip type.
- Runtime type: WPF is a Windows desktop technology. If an error specifically requests the Windows Desktop Runtime, follow that requirement; installing only the SDK or another runtime type may not be enough to launch the app.
- Fonts and scaling: Check the server list, settings dialogs, and long text at your usual display scaling. If content is clipped, check the window size, system scaling, and font environment first rather than assuming it’s a network issue.
- Desktop integration: On Linux, the desktop environment, tray extensions, and session type can affect whether the icon appears. macOS security prompts and permissions may also need attention. Don’t disable system-wide security protections as a troubleshooting step.
TUN mode also involves virtual network interfaces, routing, and permissions—it’s more than a toggle in the window. If the system proxy works but TUN fails to start, check permissions and core logs separately. Enabling TUN, complex DNS, and multiple routing rules at the outset just to compare the two UIs will make troubleshooting harder.
How to Compare Connection Speed: Keep the Core, Server, and Local Port the Same
Claims like “the Avalonia version is faster” or “the WPF version has lower latency” can’t be inferred from the framework name. Server route, core, routing rules, DNS handling, and test destination all affect connection performance. To compare the UI, look at startup time, list scrolling, and window responsiveness. To compare network performance, first make sure both versions use the same conditions.
These ports illustrate the test method; they are not necessarily the default listening ports in every version. Some configurations use a mixed inbound that accepts multiple proxy protocols on one port, while others have no separate HTTP inbound. Check the current client settings and core startup logs before entering an address in a browser or command line.
- Exit the old version and its core, then confirm the old processes have stopped to prevent both clients from competing for the same listening address and port.
- In the new version, import just one matching server entry and use the same core version. Keep routing simple for now, and don’t switch TUN and DNS setups at the same time.
- Use the same test destination and record whether the connection succeeds and what errors appear in the logs. A single latency change is not enough to show that the UI framework affects connection quality.
- Once the basic connection works, restore your original routing and traffic handling one setting at a time. Test after each change to make differences easier to pinpoint.
A core listening on a port only means the local entry point is running; enabling the system proxy does not guarantee every app will use it. Some apps have their own proxy settings, so check them separately. If the system proxy isn’t working, don’t switch UI versions before checking the settings.
Moving from WPF to Desktop: Back Up Subscriptions, Servers, and Rules Separately
Keep a restorable backup before migrating. Configuration structures can change between releases, so you can’t assume the entire data directory can be copied directly across versions or operating systems. Subscription URLs and server share links are usually easier to import again, but they don’t include every local preference. Record custom routing, DNS, core selection, and shortcuts separately.
- Back up first: Exit the old client, save the data directory it actually uses, and note the current version, core, and proxy handling setup. Data may not be stored alongside the program, so check the directory details for your version.
- Install separately: Put the new version in a separate directory or follow its installation process. Don’t overwrite the old version’s data on first launch. Subscription URLs may contain access tokens, so don’t include them in public screenshots or support requests.
- Import in stages: Restore one server entry and test it first, then add your subscriptions. Once you’ve confirmed subscription updates work, restore local groups and custom routing.
- Reconfigure OS-specific settings: When moving between operating systems, select the core files and paths again. Windows paths won’t work unchanged on Linux or macOS. Recheck shortcuts, startup behavior, and system proxy settings too.
- Verify proxy restoration on exit: Enable the system proxy, test access, then exit normally and confirm the proxy returns to the expected state. Keep the old backup until your commonly used apps and routing rules have all passed testing.
Manually copying a configuration file while the client is writing to it can leave you with an incomplete copy. Letting two versions share one data directory also increases the risk of overwriting each other’s changes. If the new version can’t read the old configuration, use a supported import method to rebuild it. Don’t edit internal data structures just because some field names look familiar.
Common Questions: Similar Interfaces Don’t Mean Identical Environments
On Windows, which version should I download first?
Start by checking the download page for the correct OS, architecture, and version. If you don’t need cross-platform support, try WPF first and test importing, the system proxy, and proxy restoration on exit. If display scaling or interactions don’t suit you, try the Avalonia desktop version in a separate directory. There’s no need to keep both running at once.
Will my existing servers stop working if I switch to the desktop version?
Changing the UI alone won’t invalidate your remote account. First check the server address, port, user ID, transport, and TLS parameters, then verify the selected core. If the same entry only fails in one version, compare the actual configuration and logs instead of immediately resetting all subscriptions.
Can I open both versions at once to compare their interfaces?
Even when you’re only looking at the UI, remember that the core may start automatically. If both processes bind to 127.0.0.1:10808, one may fail because the address is already in use. If both modify the system proxy, they may overwrite each other’s settings. A safer comparison is to exit one version before starting the other.
The desktop version launches, but the tray icon is missing. What should I do?
First, confirm the process is still running, then check the system notification area or tray support in your desktop environment. Keep the main window open for now and test whether closing the window and quitting the app are separate actions. Don’t repeatedly launch multiple instances, and don’t mistake a missing tray icon for a subscription issue.
The setting names differ between versions. Can I still follow an older guide?
Look for the setting by what it does, not by matching button names mechanically. First determine whether you need to change the local listening port, system proxy, or routing rules, then find the corresponding option in your version’s settings. When troubleshooting, note both the client and core versions; “desktop version” alone isn’t enough detail.
The choice comes down to three things: your operating system determines which branch is available, your workflow determines your UI preference, and the core and configuration determine connection capabilities. Keep a working setup intact and test another version separately; that makes it easier to identify the real differences than installing over your current version. For a broader platform comparison, see Client Comparison. To review routing and DNS concepts, see Configuration Guide.