· Clients · About 8 min read

Which v2rayN Desktop Version Should You Choose? Avalonia vs. WPF

v2rayN offers a Windows-only WPF build and a cross-platform Avalonia desktop build. Compare their UI frameworks, OS support, tray behavior, and package names, then find the right version for your platform.

At a glance

Choose the Avalonia build for macOS and Linux. For a first-time Windows install, start with the cross-platform desktop build; if the classic interface is familiar and your WPF build works well, you can stick with it. This guide covers checking package architecture, confirming whether the app stays open after you close its window, and preserving subscriptions and verifying local proxy settings when switching builds.

UI framework differences: Avalonia or WPF?

Avalonia cross-platform desktop build

Recommended

Avalonia is a cross-platform UI framework. Windows, macOS, and Linux each have their own release package; a single installer does not run on all three systems.

Best for: First-time installs or a consistent interface across desktop operating systems

WPF for Windows

WPF is a UI framework for Windows desktop apps. Choose it to keep the familiar windows, menus, and tray behavior—not to change node protocols.

Best for: Windows-only use when your existing WPF setup and workflow are working well

The UI manages subscriptions, edits nodes, and starts the core; the core handles connections. Avalonia and WPF are neither protocol names nor core names. If a node stops connecting after you switch builds, check the selected node, running core, and logs first, then compare routing and local port settings. A different-looking interface does not indicate different protocol support or connection speed.

Package names: check the OS, then the architecture

Break down the filename: the OS and architecture determine whether a package runs on your device, the UI variant tells you which desktop interface it uses, and the file extension distinguishes formats such as installers and archives. On Windows, x64 does not mean WPF, and .exe alone does not identify the cross-platform desktop build. If two downloads have the same architecture, use the variant named on the download card.

Operating systemUI variantBefore you download
WindowsAvalonia or WPFGo to Settings → System → About and check System type. An x64-based processor requires x64; on an ARM device, first check whether the selected variant offers a native ARM64 package.
macOSAvaloniaCheck the chip or processor in About This Mac. Choose ARM64 for Apple silicon and x64 for an Intel processor.
LinuxAvaloniaRun uname -m. x86_64 corresponds to x64, and aarch64 to ARM64. Then choose a package format supported by your distribution.

If you downloaded an archive, extract all of it to a new directory that your account can write to, then launch the app. Don’t pull out and run just the launcher. For builds that require a separately installed runtime, check the package notes and startup message for the runtime type and architecture. For example, if a WPF build reports that Microsoft.WindowsDesktop.App is missing, look for the matching .NET Desktop Runtime rather than installing an arbitrary version of the base runtime.

Tray behavior: closing the window may not quit the app

Check background status for your desktop environment

Windows: check the notification area
  • After closing the window, expand the taskbar’s hidden icons and check whether the v2rayN icon is still there.
  • Try restoring the window from the tray icon. Before switching builds, choose Exit from the tray menu, then use Task Manager to confirm the old process has stopped.
macOS and Linux: check for a desktop status icon
  • On macOS, check the menu bar at the top of the screen. Don’t confuse the app icon in the Dock with its menu bar status icon.
  • On Linux, first check that your desktop panel supports status icons. If you can’t see one, use the system monitor to check whether the process is running. Don’t launch multiple instances to find out.

First confirm whether the app has quit, then check whether the system proxy still points to a local listening address. Verify these separately.

Whether you can find the tray icon depends on your desktop environment, icon display settings, and app preferences. To check, open the main window, close it once, then try restoring it from the tray or menu bar. If you only want to stop proxying, turn off the system proxy or TUN setting configured by the client, then explicitly quit the app. If you set up a manual proxy, restore the previous address instead of clearing the system settings.

Switching builds: keep your subscriptions and check local ports

Before switching, note your subscription source, active node, routing mode, and local listening ports. Treat subscription URLs as credentials and don’t share them in public screenshots. To keep manually added nodes, use the client’s import/export feature or back up the original data directory. Don’t have the old and new apps write to the same directory at the same time.

127.0.0.1
Example of a loopback address
10808
Example of a local listening port
  1. Quit the old build before launching the new one. Import a subscription or a known-working node, then select the same test node you used with the old build to avoid mistaking node differences for a build-switch issue.
  2. Check the local listening settings under Settings → Parameter Settings, then confirm in the logs that the core has started. The 127.0.0.1:10808 example above shows how an address and port form a proxy endpoint; use the protocol and port from your actual configuration.
  3. First test with a browser that follows the system proxy settings, then try any terminal or other apps where you configured a manual proxy. If the new build uses a different port, update it in those apps too. If the logs report that a port is already in use, check whether the old instance is still running instead of launching more instances.

Once your nodes, routing, and frequently used apps are working, decide whether to delete the old directory. To roll back, quit the new build, restore the previous proxy settings, then launch the old build. Keeping the old build in a separate directory with a backup makes it easier to identify differences than overwriting its files.

Common questions about the v2rayN desktop builds

Can I keep both builds on Windows?

Yes. Put them in separate directories and run only one instance at a time. Before switching, quit the current build and confirm its local ports are free, then launch the other one to avoid both builds changing your system proxy settings.

Do I need to buy a new subscription after switching to the cross-platform build?

No. Changing the UI variant alone doesn’t require a new subscription. Add your existing subscription to the new build and update it. If the update fails, check that the URL is still valid and whether your provider limits subscription formats or device count.

The package closes as soon as I open it. Should I switch to WPF?

Not as a first step. Check your OS and architecture, make sure the archive was fully extracted, and confirm your account can write to the app’s data directory. On Windows, if you see a runtime error, check the startup message or Event Viewer under Windows Logs → Application, then address the specific missing component.

After switching from WPF to Avalonia, web pages load but my terminal can’t connect. What should I check?

First check whether the terminal still has old http_proxy or https_proxy settings, then compare the port and proxy type. Reopen the terminal after changing environment variables and test again. A successful browser test doesn’t prove the terminal is using the same proxy endpoint.

Download and install the client