Skip to content
Get packs

Guide · Open source

How to use Avalonia: install packages and build your first app

Updated · written with AI from the project's own documentation and checked against our catalogue data

Avalonia is an open-source, cross-platform UI framework for .NET. You describe screens in XAML, write the logic in C#, and the same app can run on Windows, macOS, Linux, iOS, Android and WebAssembly. This guide walks through installing it, where to find the official tutorial and samples, and whether it suits your project, so you can start a first app with confidence.

AvaloniaAvaloniaUI/Avalonia · ★ 31.7k · MIT

Quick start

  1. 1Install the .NET SDK. Install a .NET SDK. The README does not state a required version, so confirm it in the official docs.
  2. 2Add the Avalonia packages. In the NuGet Package Manager console, run Install-Package Avalonia and Install-Package Avalonia.Desktop.
  3. 3Set up your editor. Install the Avalonia extension for VS Code, the Visual Studio extension, or the Rider support, depending on your IDE.
  4. 4Follow the Get Started guide. Open docs.avaloniaui.net/docs/get-started and work through the starter tutorial.
  5. 5Explore the samples. Clone or browse the Avalonia.Samples repository to see working examples of common patterns.
  6. 6Check the build instructions if you contribute. If you want to build Avalonia itself, the README points to docs/build.md.

What do you need before you install Avalonia?

Avalonia is built for C# developers on the .NET platform. You need the .NET SDK installed. The README excerpt does not specify which SDK version is required, so check the official documentation for the current requirement before you start.

If you already know XAML or WPF, the programming model will look familiar. The README says Avalonia is similar to WPF but not a 1:1 copy, so expect some differences.

  • A .NET SDK (version not specified in the README excerpt)
  • Familiarity with C# and XAML helps, especially if you have used WPF

How do you install Avalonia packages?

Avalonia is delivered through NuGet. Open the Package Manager console in your project and run the commands below to install the core package and the desktop package.

The packages are listed at https://www.nuget.org/packages/Avalonia/.

Install-Package Avalonia Install-Package Avalonia.Desktop

Which editor tools can you use with Avalonia?

The README lists tooling for three environments. Visual Studio Code has the Avalonia for Code extension, which provides XAML previewing, code completion, diagnostics and code navigation.

Visual Studio 2022 and 2026 have the Avalonia Visual Studio Extension, which includes project and control templates, a live XAML previewer, code completion and diagnostics.

JetBrains Rider supports code completion, inspections and refactorings out of the box. XAML previewing needs a third-party, community-maintained plugin called AvaloniaRider.

  • VS Code: Avalonia for Code extension (AvaloniaTeam.vscode-avalonia)
  • Visual Studio 2022 and 2026: Avalonia Visual Studio Extension (AvaloniaTeam.AvaloniaVS)
  • Rider: built-in support, plus the community AvaloniaRider plugin for XAML preview

Where do you learn Avalonia step by step?

The official Get Started guide is at https://docs.avaloniaui.net/docs/get-started. The documentation lives at https://docs.avaloniaui.net, and there is a starter tutorial for newcomers at https://docs.avaloniaui.net/docs/get-started/starter-tutorial.

For working code, the Avalonia.Samples repository on GitHub contains a range of samples.

  • Get Started guide: docs.avaloniaui.net/docs/get-started
  • Starter tutorial: docs.avaloniaui.net/docs/get-started/starter-tutorial
  • Samples: github.com/AvaloniaUI/Avalonia.Samples

Should you use the nightly build or the NuGet release?

The nightly build feed tracks the current state of master. The README notes that these packages are less stable than the release on NuGet.org, but you get the latest features and bugfixes sooner.

For most projects, start with the NuGet release. Use the nightly feed only if you need a specific fix or feature that has not shipped yet. The README points to a wiki page on using the nightly feed.

What should you know about Avalonia 11 and 12?

The README links to a list of breaking changes between Avalonia 11 and Avalonia 12. Read that list before you upgrade an existing project, or when you follow tutorials written for an earlier version.

What people use it for

  • Building internal line-of-business tools on .NET
  • Shipping one UI codebase across desktop and mobile
  • Creating commercial desktop applications in C#
  • Running a .NET UI in the browser via WebAssembly
  • Porting developers from WPF to a cross-platform model

Frequently asked questions

Is Avalonia free to use?

Avalonia is licensed under the MIT licence, as stated in the README. The separate Avalonia XPF product for running WPF apps on macOS and Linux is a commercial product licensed per app and per platform.

How do I install Avalonia?

Install the packages from NuGet using the Package Manager console. Run Install-Package Avalonia and Install-Package Avalonia.Desktop in your project.

Is Avalonia the same as WPF?

The README says Avalonia is similar to WPF and is considered its spiritual successor, but it is not a 1:1 copy. It has improvements, so WPF knowledge transfers well but code may need changes.

Can I run a WPF app on macOS or Linux with Avalonia?

Not with the open-source Avalonia package alone. The README points to Avalonia XPF, a commercial product that enables WPF apps to run on macOS and Linux with little to no code changes.

Do I need to know C# to use Avalonia?

Yes. The README says the framework centres on writing C# and XAML, and it is built for C#. It is not suited to a non-.NET language stack or a no-code builder.

Which platforms does Avalonia support?

The README lists Windows, macOS, Linux, iOS, Android and WebAssembly.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Avalonia suits C# developers who know XAML or WPF and want one UI codebase across desktop, mobile and the browser under an MIT licence. If you want a visual no-code builder, a non-.NET language, or an unchanged WPF app on macOS or Linux without paying for a commercial product, look at other options such as the comparable projects WPF, .NET MAUI, Uno Platform or Eto.Forms.

Install options & downloads