v2rayN Desktop (Avalonia) vs. WPF: Which Windows, macOS, or Linux Package Should You Install?

Desktop vs. WPF: The difference is the UI, not the subscription format

Avalonia is a cross-platform desktop UI framework, while WPF is designed for Windows. v2rayN Desktop uses Avalonia and is available for Windows, macOS, and Linux; the WPF version is for Windows. Cross-platform means the project can publish separate builds for different operating systems—not that one installer runs on all three.

v2rayN manages subscription groups, node selection, routing, and core processes. The selected core establishes the proxy connection. Whether protocols such as VMess and VLESS work depends on the core version, node transport settings, and server configuration—not on whether Avalonia or WPF draws the window. Changing the UI won’t fix an outdated subscription or add protocol support to an incompatible core.

Choosing an installer for Windows, macOS, or Linux

Check three things when downloading: operating system, processor architecture, and package format. In filenames, x64 usually means a 64-bit Intel or AMD desktop processor; arm64 means a 64-bit ARM processor. Both are 64-bit, but they aren’t interchangeable. Whether the package includes a runtime is a separate detail—check the download page.

The recommendation below applies to users who want a similar interface across multiple desktop operating systems. It doesn’t mean Desktop is always a better fit than WPF on Windows. Check the download center for the available architectures and package types.

• Windows: Open Settings → System → About and check “System type.” Confirm whether your system is x64 or ARM64, then choose the matching Desktop or WPF package.
• macOS: Open About This Mac from the Apple menu and check “Chip” or “Processor.” Choose an arm64 build for Apple silicon or an x64 build for an Intel Mac. Don’t download the Windows package.
• Linux: Check your architecture first, then choose an available package type that fits your distribution and desktop environment. Being able to extract an archive doesn’t mean the app and its dependencies will run.

On macOS and Linux, you can check your architecture in Terminal. This command only reads system information and won’t change network settings:

uname -m

x86_64 usually corresponds to x64; arm64 or aarch64 corresponds to 64-bit ARM. On Linux, check the package notes to confirm required graphics libraries, runtimes, and system libraries are available. Matching the architecture is only the first step.

Test the interface, system tray, and background behavior separately

Desktop and WPF may differ in font rendering, list density, scaling, menu placement, and keyboard shortcut feedback. If text looks too large or dialogs extend off-screen on a high-resolution display, first check system scaling and scaling settings across monitors. Then determine whether the issue is with the client UI. Don’t start by deleting subscriptions or routing settings.

Closing a window doesn’t necessarily quit the app. Whether it minimizes to the tray or leaves a core process running depends on client settings and system tray support in your OS. Linux desktop environments vary widely in their support for status icons, so a missing icon doesn’t prove the core has stopped.

1. Keep the main window open on first launch: Select a node and check the logs for a successful core startup. If it fails, note the error message first.
2. Check what happens when you close the window: Click the close button, then use Task Manager or your system’s process tool to see whether the client is still running.
3. Check the tray: On Windows, look in the hidden notification area icons; on macOS, check the menu bar; on Linux, see whether your desktop environment supports status icons.
4. Verify a normal exit: Quit from the app menu or tray menu when possible. Then check that the system proxy is back to the expected state. Don’t force-quit the process as your usual way to exit.

Moving from WPF to Desktop: Handle subscriptions and system settings separately

Back up your existing data before migrating. Include subscription URLs, group details, custom routing, and any essential settings. This information may contain access credentials, so store it securely. Don’t copy every configuration file from the old folder over the data directory for another build or version; internal formats and paths may not be compatible.

A subscription update provides node details from the service provider; it doesn’t sync all local settings from the old client. Check group update intervals, custom rules, keyboard shortcuts, and window behavior individually. When moving between operating systems, don’t reuse old absolute paths as-is.

If you keep both apps on the same device, run only one at a time. Two processes may compete to control the system proxy, listen on the same port, or create a virtual network adapter, making problems harder to diagnose. After testing, decide which instance to keep and check startup settings so the old one doesn’t take over again after a reboot.

After installation, test the local proxy first, then check system proxy and TUN

“The UI opens” and “the proxy works” are two separate checks. The first means the graphical app has started; the second also requires a working core executable, valid node settings, a local inbound, and correct routing. If you’re told a runtime is missing, install the dependency listed in the package notes or choose a suitable package. If the core fails to start, check its logs instead of blaming Avalonia.

1. Check core status: Review the startup logs and first rule out a missing core, insufficient execution permissions, or a port conflict. On Linux, check that the app’s location allows executables to run.
2. Check the local inbound: Open Settings → Parameter Settings and check the actual listening address, port, and inbound type. The layout may vary between versions, so use the values shown in the UI.
3. Test the proxy separately: Make a request with the proxy address specified explicitly to rule out interference from apps that may not read the system proxy settings.
4. Test the system proxy: Once the local inbound works, configure your browser to use the system proxy. The system proxy doesn’t force every app to use a proxy.
5. Test TUN last: Enable it only if you need to capture traffic from apps that aren’t proxy-aware. Check system permissions, routing, and DNS. TUN capturing traffic doesn’t mean every destination will use the proxy route.

Here’s an example using a SOCKS inbound at 127.0.0.1:10808 that you’ve confirmed is listening locally. This is only a test example, not a guarantee of the default port in your installation. If the UI shows a different port, replace it. On Windows, use curl.exe in Terminal to call curl explicitly; on macOS and Linux, use curl.

curl --proxy socks5h://127.0.0.1:10808 --head --connect-timeout 10 https://example.com/

socks5h sends domain name resolution through the proxy, while --connect-timeout 10 sets a 10-second timeout for the connection phase. This request can help check whether the current route reaches the destination, but one response can’t confirm that all routing and DNS settings are correct. If it immediately reports that the local port is unreachable, check whether the port is listening. If it times out after connecting, check the node, exit route, and destination connectivity.

Package selection and migration FAQs