For a first-time install, start with the Avalonia desktop version. If your WPF setup is working well on Windows, there’s no need to switch. When changing versions, migrate your nodes first, then check the core, routing, and system proxy settings. You don’t need to copy every old setting just to keep the interface consistent.
Platform support: Choose either version on Windows; use the desktop version on macOS or Linux
Avalonia and WPF are UI frameworks. They determine how the app’s windows and controls are displayed and which desktop operating systems it can run on. Whether VMess or VLESS connects depends on the core, node settings, and server configuration. Don’t mistake the framework name on the installer for the name of the core.
First-time install or existing setup?
Avalonia desktop version
RecommendedRuns on Windows, macOS, and Linux. You can use the same approach to manage subscriptions and nodes across systems, but check the tray menu, system proxy, and permissions for each OS.
Best for: first-time installs or using v2rayN across different desktop operating systems
WPF version
Windows only. If your current version supports the protocols you need and your routing rules are verified, there’s no need to reconfigure everything just to switch UI frameworks.
Best for: keeping a well-configured Windows setup
Installers and runtime requirements: check the OS, architecture, and runtime
Check the computer running the client before downloading—not the operating system on the node server. On Windows, find System type under Settings → System → About. On macOS, check About This Mac to see whether you have an Apple silicon or Intel processor. On Linux, run uname -m: x86_64 usually means x64, while aarch64 means ARM64.
- Windows: Both Windows downloads listed here are x64. Once you’ve confirmed your architecture, choose the Avalonia desktop version or the classic WPF version based on your preference.
- macOS: Choose the ARM64 DMG for Apple silicon or the x64 DMG for Intel. Both packages are for the Avalonia desktop version; the difference is the processor architecture.
- Linux: After matching the package to your architecture, choose DEB for systems such as Debian and Ubuntu, or RPM for systems such as Fedora. A compatible package format doesn’t guarantee that your distribution meets every declared dependency.
Whether you need to install .NET depends on whether the specific release package includes a runtime—not just on whether it uses Avalonia or WPF. If Windows reports that Microsoft.WindowsDesktop.App is missing, check the required version and architecture, then install the matching .NET Desktop Runtime—not just the base runtime for the same release. If the main window opens but an error appears only after starting a node, check the core logs first; a core startup failure isn’t a missing UI runtime.
Feature differences: test the core, routing, and traffic entry points separately
Seeing the same nodes after switching versions only confirms that the node data was imported. To compare behavior, use the same node and check the core type first, then compare routing and traffic entry points. If you change the UI, core, and test node all at once, a change in latency won’t tell you which one caused it.
- Core and protocol: Select a node that worked before, check its protocol, transport, and security settings, then confirm which core actually starts in the logs. A VLESS node’s transport and security parameters must still match the server. Switching to Avalonia won’t fill in those fields for you.
- Routing: Check the selected rule set under Settings → Routing settings. After importing custom rules, verify their order and make sure all referenced rule assets are present. Test one destination expected to connect directly and another expected to use the proxy; don’t treat one working website as a complete test.
- Traffic entry points: Check the System proxy status in the main window or tray menu. Test with an app that follows the system proxy before deciding whether to test TUN separately. The system proxy doesn’t automatically route traffic from every app. TUN requires platform permissions and network configuration, so it shouldn’t be the first thing you test when troubleshooting.
Example ports for running both versions at once
These ports illustrate a conflict; they aren’t fixed values for either version. Check the local listening port under Settings → Parameter settings. If the old version is already using the same address and port, the new version may open normally but then report a listening error. The simplest approach is to exit the old version from the tray before migrating. If you need to test both at once, check all other enabled listeners as well as the main port, and let only one instance change the system proxy.
Configuration migration: resubscribe to restore subscriptions; check manual settings separately
First, identify where your nodes came from. To restore a subscription group, add its subscription URL in the new version, then update it from the Subscription groups menu. Manually added nodes aren’t included in subscriptions, so save their share links separately or make a local backup. Subscription URLs and node share links may contain access credentials; keep them somewhere you control and don’t include them in public screenshots or troubleshooting posts.
Choose a migration approach
Switching versions on the same Windows PC or moving to another desktop OS
Switching from WPF to Avalonia on Windows
- In the old version, clear the system proxy, turn off TUN if enabled, and exit from the tray. Then back up the data directory the old version actually uses.
- Try the new version in a separate location. Before restoring data files, confirm that the two versions use compatible data formats and directory layouts, and keep an untouched copy of the new version’s original data.
- Use your notes from the old version to restore routing and local ports. If you get a read error, restore the new version’s own data first, then recreate your nodes from subscriptions and share links.
Moving from Windows to macOS or Linux
- Install the Avalonia package for the target system and architecture, then add your subscriptions again and import any necessary manually added nodes.
- On the target system, configure rule file locations, apps’ manual proxy addresses, and startup settings again. Don’t copy Windows-specific paths.
- First, test a standard proxy connection and check the routing results. Configure and test TUN separately on the target system only if you need to route traffic from the whole device.
Consider the migration successful when the new version starts on its own, connects to a node, and routes traffic as expected. Once you’ve confirmed all three, decide whether to remove the old version.
Troubleshooting: connection failures, missing nodes, or apps bypassing the proxy
Troubleshoot by symptom
Why does the new version still report a port conflict after I close the window?
The old version may still be running in the tray after you close its window. Find its tray icon, select Exit, then restart the core in the new version. If the port is still in use, check the conflicting port under Settings → Parameter settings. If you change it, update any apps where you entered the proxy address manually.
Why are some nodes missing even though the subscription updated successfully?
First, select the same subscription group, confirm the URL matches, and check the group’s filter settings. Then see whether the missing nodes in the old version were added manually. Subscription updates don’t sync manually added nodes to the new version; import those separately.
Why does my browser work, but another app can’t connect?
First, check whether the app uses the system proxy. If it supports a manual proxy, set the proxy type, address, and port to match a local listener provided by the client. Test TUN separately only if the app can’t use these options and you need to route its traffic.
How do I switch back to WPF if the new version isn’t a good fit?
In the new version, clear the system proxy, turn off TUN, then exit from the tray. Start WPF from the preserved old directory, check the current node and routing, and then restore your original system proxy settings. If both versions shared a data directory, restore the old version’s data from the backup you made before migrating.