Avalonia: a cross-platform .NET UI framework for XAML developers leaving Windows-only WPF

The problem Avalonia addresses: one XAML codebase instead of one per platform

A .NET team that wants a desktop application on Windows, macOS and Linux has historically had a small set of options, and most of them force a choice between native look and a single codebase. Avalonia's answer is a UI framework written for .NET that renders its own controls across all of those targets, so the same XAML and the same view models compile and run on each. The README states support for Windows, macOS, Linux, iOS, Android and WebAssembly, which means the same project structure can also produce a mobile build and a browser build. The intended audience is stated plainly: XAML developers, specifically those coming from WPF. The README calls Avalonia "the spiritual successor to WPF" and notes that it is similar to WPF but not a 1:1 copy. That framing matters for scoping. This is not a framework for teams who want to write platform-specific UI per target, and it is not a web framework with a .NET backend. It is a rendering and layout stack with its own styling system, aimed at people who already think in XAML.

What the repository actually contains, and what the README leaves out

The repository is C# on the main branch, MIT licensed, with an active release cadence: 11.3.21 and 12.1.2 both appeared in September 2026, and 11.3.20 landed in August 2026. Two version lines moving at once is worth noting. Anyone starting fresh has to decide whether to target 11.3 or 12.1, and the README points to a documentation page listing breaking changes between the two. The README does not describe the rendering backend, the layout engine, the threading model or the composition pipeline. It links to docs.avaloniaui.net for that. It also does not describe the package split beyond two example install commands, so a reader cannot tell from the README alone which NuGet packages are required for a mobile target versus a desktop one. If you are evaluating Avalonia from the repository front page, you will get the platform list, the licence, the editor tooling and the install commands, and you will need the documentation site for everything architectural.

How the framework is put together: packages, targets and tooling

The visible architecture is a layered set of NuGet packages rather than a single monolith. The README's manual install instructions are two commands in the Package Manager console: Install-Package Avalonia and Install-Package Avalonia.Desktop. That split is informative. The core package carries the framework, and Avalonia.Desktop is a separate package for desktop targets, which implies further per-target packages exist for mobile and WebAssembly even though the README does not list them. Styling is described as a flexible styling system, which is the part WPF developers will recognise as diverging from WPF's resource and style model. Tooling sits alongside the framework rather than inside it: a VS Code extension providing XAML previewing, completion, diagnostics and navigation; a Visual Studio extension with project and control templates plus a live XAML previewer; and for JetBrains Rider, code completion, inspections and refactorings work out of the box while XAML previewing requires the community-maintained AvaloniaRider plugin. That last detail is the kind of thing that decides a team's editor choice, and it is stated explicitly in the README rather than buried.

Getting a project running: the commands the README gives

The README does not provide a dotnet new template invocation, so the shortest documented path to a working project is the editor extensions plus the package commands. In the Visual Studio Package Manager console, the two commands are Install-Package Avalonia and Install-Package Avalonia.Desktop. The README directs readers to the Get Started guide at docs.avaloniaui.net for the fuller walkthrough, and to a starter tutorial for newcomers. It also points at a separate samples repository, AvaloniaUI/Avalonia.Samples, for working code. For Rider users the setup is a two-step: code completion and inspections work without configuration, and XAML previewing requires adding the JetBrains plugin repository URL and installing the AvaloniaRider plugin. There is also a nightly build feed documented in the repository wiki, which the README says tracks the current state of master and which, in its words, "many of our users actually prefer". Treat that as a real option only if you can absorb churn, since the README itself notes those packages are less stable than the NuGet.org release.

The WPF migration path is a separate, commercial product

This is the part most likely to be misread. Avalonia is MIT licensed. Avalonia XPF is not. The README describes XPF as enabling WPF applications to run on macOS and Linux "with little to no code changes" and states it is a commercial product licensed per-app, per-platform. So there are two distinct migration stories. If you are rewriting or starting fresh, you use the MIT-licensed framework and accept that the XAML is similar to WPF but not identical. If you have a large existing WPF application and want it on macOS and Linux without a rewrite, the README's answer is XPF, and the pricing model is per application and per platform you ship to. That is a licensing decision, not a technical one, and it should be made before any code is written. The README does not publish XPF pricing, so that has to be obtained from the vendor.

Where Avalonia is the wrong choice, and what competes with it

The clearest limitation is stated by the project itself: Avalonia is similar to WPF but not a 1:1 copy. A team expecting to paste WPF XAML and have it compile will spend time on the differences, and the existence of a dedicated breaking-changes page between versions 11 and 12 suggests the framework's own APIs move between major releases. The second limitation is support. The README documents a security contact address, security@avaloniaui.net, and notes that Avalonia does not operate a bug bounty programme. There is no mention of commercial support tiers for the open source framework, only sponsorship, with Devolutions named as a sponsor. Teams that need an SLA around the core framework will not find one described here. The natural alternative is .NET MAUI, which is Microsoft's own cross-platform UI stack for .NET and ships inside the .NET release train. The difference in approach is that MAUI maps controls onto each platform's native widgets, while Avalonia draws its own controls and exposes a XAML dialect closer to WPF. The practical consequence: MAUI gives you platform-native control appearance and a Microsoft support channel, whereas Avalonia gives you pixel-consistent rendering across targets and a styling system that behaves the same everywhere. Which one is right depends on whether visual consistency across platforms or native look per platform matters more to your users.

Maintenance cost, version lines and licence implications

Two release lines are being maintained in parallel, 11.3.x and 12.1.x, based on the release list. That is a maintenance cost you inherit: bug fixes may land on one line before the other, and the breaking-changes documentation between 11 and 12 tells you the upgrade is not free. The README does not state a support window for the 11.x line, so if you start on 11.3.21 you should confirm how long that line receives fixes before committing. On the licence side, the framework is MIT, which the README states directly and links to a licence file. MIT is permissive and carries no per-app or per-platform obligation. The commercial obligations attach to Avalonia XPF, not to Avalonia itself, and the README is explicit that XPF is licensed per-app, per-platform. This article is not legal advice; if you plan to ship XPF, read the actual licence terms rather than the README summary. For the open source framework, the licence is the least complicated part of the adoption decision.

Editorial conclusion

Adopt Avalonia if you are a XAML team that needs one codebase across Windows, macOS, Linux, iOS, Android and WebAssembly and you accept that the framework is not a 1:1 WPF copy. Do not adopt it if you need a commercial support contract around the core framework itself, or if your goal is to move an existing WPF application without touching code, since that path runs through Avalonia XPF, which the README describes as licensed per-app, per-platform. Verify first which major version you are starting on: the repository ships 11.3.x and 12.1.x releases in parallel, and the documentation publishes a dedicated page of breaking changes between Avalonia 11 and Avalonia 12.

Official sources

1. AvaloniaUI/Avalonia on GitHub
2. License: MIT
3. Project website
4. README
5. Releases