Publishing and Deployment

Overview

Avalonia UI applications can be deployed to multiple platforms from a single codebase. This guide covers building, packaging, and deploying your applications for desktop, mobile, and web platforms.

Prerequisites

Install .NET SDK

Install the .NET SDK version compatible with your Avalonia project. Check your project’s global.json file for the required version:

{
  "sdk": {
    "version": "10.0.101",
    "rollForward": "latestFeature"
  }
}

Download the SDK from dotnet.microsoft.com.

Install platform workloads

.NET requires platform-specific workloads for targeting different platforms:

dotnet workload install android ios maccatalyst wasm-tools

On Unix systems, you may need to run this command with sudo.

For Tizen support:PowerShell:

(New-Object System.Net.WebClient).DownloadString('https://raw.githubusercontent.com/Samsung/Tizen.NET/main/workload/scripts/workload-install.ps1') | Invoke-Expression

Bash:

curl -sSL https://raw.githubusercontent.com/Samsung/Tizen.NET/main/workload/scripts/workload-install.sh | sudo bash

Building Desktop Applications

Windows

Development Build

Build for local testing:

dotnet build -c Release

Self-Contained Deployment

Create a standalone executable that includes the .NET runtime:

dotnet publish -c Release -r win-x64 --self-contained true

Framework-Dependent Deployment

Smaller deployment that requires .NET runtime to be installed:

dotnet publish -c Release -r win-x64 --self-contained false

Single File Application

Package everything into a single executable:

dotnet publish -c Release -r win-x64 \
  --self-contained true \
  -p:PublishSingleFile=true \
  -p:IncludeNativeLibrariesForSelfExtract=true

macOS

Build for macOS

dotnet publish -c Release -r osx-x64 --self-contained true

On macOS, you need Xcode installed to build native libraries.

Build Native Libraries

For Apple Silicon and Intel Macs:

./build.sh CompileNative

This builds and installs the native libraries that .NET requires at compilation and runtime.

Create App Bundle

Create a proper .app bundle for macOS:

<PropertyGroup>
  <RuntimeIdentifier>osx-x64</RuntimeIdentifier>
  <UseAppHost>true</UseAppHost>
  <CFBundleName>MyApp</CFBundleName>
  <CFBundleDisplayName>My Application</CFBundleDisplayName>
  <CFBundleIdentifier>com.mycompany.myapp</CFBundleIdentifier>
</PropertyGroup>

Linux

Build for Linux

dotnet publish -c Release -r linux-x64 --self-contained true

Supported Linux Backends

Avalonia supports multiple rendering backends on Linux:

X11: Traditional Linux window system
Framebuffer: Direct framebuffer rendering for embedded systems
DRM: Direct Rendering Manager for hardware-accelerated graphics

It’s not possible to build the complete project on Linux/macOS. You can only build the subset targeting .NET Standard and .NET Core, which is sufficient for UI functionality.

Cross-Platform Runtime Identifiers

Common runtime identifiers (RIDs):

Platform	Runtime Identifier	Architecture
Windows x64	`win-x64`	64-bit Intel/AMD
Windows x86	`win-x86`	32-bit Intel/AMD
Windows ARM64	`win-arm64`	64-bit ARM
macOS Intel	`osx-x64`	64-bit Intel
macOS Apple Silicon	`osx-arm64`	64-bit ARM
Linux x64	`linux-x64`	64-bit Intel/AMD
Linux ARM	`linux-arm`	32-bit ARM
Linux ARM64	`linux-arm64`	64-bit ARM

Building Mobile Applications

Android

Build Android APK

dotnet build -c Release -f net8.0-android

Publish Android APK

dotnet publish -c Release -f net8.0-android

Create Signed APK

Add signing configuration to your .csproj:

<PropertyGroup Condition="'$(TargetFramework)'=='net8.0-android'">
  <AndroidKeyStore>true</AndroidKeyStore>
  <AndroidSigningKeyStore>myapp.keystore</AndroidSigningKeyStore>
  <AndroidSigningKeyAlias>myapp</AndroidSigningKeyAlias>
  <AndroidSigningKeyPass>password</AndroidSigningKeyPass>
  <AndroidSigningStorePass>password</AndroidSigningStorePass>
</PropertyGroup>

iOS

Build iOS Application

dotnet build -c Release -f net8.0-ios

iOS builds require macOS with Xcode installed.

Publish for App Store

dotnet publish -c Release -f net8.0-ios \
  -p:RuntimeIdentifier=ios-arm64 \
  -p:ArchiveOnBuild=true

Mac Catalyst

Build for Mac Catalyst

dotnet build -c Release -f net8.0-maccatalyst

Publish Mac Catalyst App

dotnet publish -c Release -f net8.0-maccatalyst \
  -p:RuntimeIdentifier=maccatalyst-x64

Building WebAssembly Applications

Prerequisites

Install Node.js from nodejs.org (latest LTS version recommended).

Build Browser/WASM Project

dotnet build -c Release -f net8.0-browser

Publish for Web

dotnet publish -c Release -f net8.0-browser

The output will be in bin/Release/net8.0-browser/publish/.

WebAssembly Project Configuration

<Project Sdk="Microsoft.NET.Sdk.WebAssembly">
  <PropertyGroup>
    <TargetFramework>net8.0-browser</TargetFramework>
    <WasmEnableThreads>false</WasmEnableThreads>
    <AllowUnsafeBlocks>true</AllowUnsafeBlocks>
    <DebuggerSupport>true</DebuggerSupport>
    <WasmDebugLevel>5</WasmDebugLevel>
  </PropertyGroup>

  <ItemGroup>
    <ProjectReference Include="../../src/Avalonia.Browser/Avalonia.Browser.csproj" />
  </ItemGroup>
</Project>

Deployment

Host the published files on any static web server:

IIS: Configure MIME types for .wasm files
nginx: Add MIME type mapping
Azure Static Web Apps: Upload publish folder
GitHub Pages: Push to gh-pages branch

Using Nuke Build System

Avalonia uses Nuke for advanced build automation.

Install Nuke

dotnet tool install --global Nuke.GlobalTool --version 6.2.1

Common Nuke Commands

Compile Project

nuke --target Compile --configuration Release

Run Tests

nuke --target RunTests --configuration Release

Create NuGet Packages

nuke --target Package --configuration Release

This command automatically compiles and runs tests before packaging.

Run Without Installing Nuke

dotnet run --project nukebuild/_build.csproj -- --configuration Release

Project Configuration

Multi-Platform Project Structure

Organize your solution for multiple platforms:

MyApp/
├── MyApp/                    # Shared code and UI
├── MyApp.Desktop/            # Desktop-specific (Windows, macOS, Linux)
├── MyApp.Android/            # Android-specific
├── MyApp.iOS/                # iOS-specific
├── MyApp.Browser/            # WebAssembly-specific
└── MyApp.sln                 # Solution file

Solution Filters

Use solution filters to work on specific platforms:

MyApp.sln: Complete solution (requires all workloads)
MyApp.Desktop.slnf: Desktop-only (no mobile workloads required)

{
  "solution": {
    "path": "MyApp.sln",
    "projects": [
      "MyApp/MyApp.csproj",
      "MyApp.Desktop/MyApp.Desktop.csproj"
    ]
  }
}

Optimization and Configuration

Trimming

Reduce application size with trimming:

<PropertyGroup>
  <PublishTrimmed>true</PublishTrimmed>
  <TrimMode>link</TrimMode>
</PropertyGroup>

Test thoroughly after enabling trimming, as it may remove required code through reflection.

Native AOT

Enable Native Ahead-of-Time compilation for better startup performance:

<PropertyGroup>
  <PublishAot>true</PublishAot>
</PropertyGroup>

Compression

Enable assembly compression:

<PropertyGroup>
  <EnableCompressionInSingleFile>true</EnableCompressionInSingleFile>
</PropertyGroup>

Platform-Specific Options

Windows Options

Configure Windows-specific features:

AppBuilder.Configure<App>()
    .UsePlatformDetect()
    .With(new Win32PlatformOptions
    {
        CompositionMode = new[] 
        { 
            Win32CompositionMode.LowLatencyDxgiSwapChain 
        }
    });

Linux Options

Configure X11 features:

AppBuilder.Configure<App>()
    .UsePlatformDetect()
    .With(new X11PlatformOptions
    {
        EnableMultiTouch = true,
        UseDBusMenu = true,
        EnableIme = true,
    });

Continuous Integration

GitHub Actions Example

name: Build and Release

on:
  push:
    branches: [ main ]

jobs:
  build:
    runs-on: ${{ matrix.os }}
    strategy:
      matrix:
        os: [windows-latest, ubuntu-latest, macos-latest]
        
    steps:
    - uses: actions/checkout@v3
    
    - name: Setup .NET
      uses: actions/setup-dotnet@v3
      with:
        dotnet-version: '10.0.x'
    
    - name: Restore dependencies
      run: dotnet restore
    
    - name: Build
      run: dotnet build -c Release --no-restore
    
    - name: Publish
      run: dotnet publish -c Release --no-build

Troubleshooting

Error: Workload not installed

Install the required workloads:

dotnet workload install android ios maccatalyst wasm-tools

Error: Cannot build on Linux/macOS

Use solution filters to build only .NET Standard/.NET Core projects:

dotnet build MyApp.Desktop.slnf

Issue: Large binary size

Enable trimming and single-file publishing to reduce size:

dotnet publish -c Release -r win-x64 \
  --self-contained true \
  -p:PublishTrimmed=true \
  -p:PublishSingleFile=true

Error: Native libraries not found (macOS)

Build native libraries first:

./build.sh CompileNative

Next Steps

Building Avalonia

Complete build instructions for contributing

Application Lifecycle

Learn about application startup and shutdown

Best Practices

Development best practices for Avalonia

Debugging

Debug your Avalonia applications effectively

Get Started

Core Concepts

Controls

Platform Support

Advanced Topics

Guides

​Overview

​Prerequisites

​Building Desktop Applications

​Windows

​Development Build

​Self-Contained Deployment

​Framework-Dependent Deployment

​Single File Application

​macOS

​Build for macOS

​Build Native Libraries

​Create App Bundle

​Linux

​Build for Linux

​Supported Linux Backends

​Cross-Platform Runtime Identifiers

​Building Mobile Applications

​Android

​Build Android APK

​Publish Android APK

​Create Signed APK

​iOS

​Build iOS Application

​Publish for App Store

​Mac Catalyst

​Build for Mac Catalyst

​Publish Mac Catalyst App

​Building WebAssembly Applications

​Prerequisites

​Build Browser/WASM Project

​Publish for Web

​WebAssembly Project Configuration

​Deployment

​Using Nuke Build System

​Install Nuke

​Common Nuke Commands

​Compile Project

​Run Tests

​Create NuGet Packages

​Run Without Installing Nuke

​Project Configuration

​Multi-Platform Project Structure

​Solution Filters

​Optimization and Configuration

​Trimming

​Native AOT

​Compression

​Platform-Specific Options

​Windows Options

​Linux Options

​Continuous Integration

​GitHub Actions Example

​Troubleshooting

​Next Steps

Building Avalonia

Application Lifecycle

Best Practices

Debugging

Build docs developers (and LLMs) love

Overview

Prerequisites

Building Desktop Applications

Windows

Development Build

Self-Contained Deployment

Framework-Dependent Deployment

Single File Application

macOS

Build for macOS

Build Native Libraries

Create App Bundle

Linux

Build for Linux

Supported Linux Backends

Cross-Platform Runtime Identifiers

Building Mobile Applications

Android

Build Android APK

Publish Android APK

Create Signed APK

iOS

Build iOS Application

Publish for App Store

Mac Catalyst

Build for Mac Catalyst

Publish Mac Catalyst App

Building WebAssembly Applications

Prerequisites

Build Browser/WASM Project

Publish for Web

WebAssembly Project Configuration

Deployment

Using Nuke Build System

Install Nuke

Common Nuke Commands

Compile Project

Run Tests

Create NuGet Packages

Run Without Installing Nuke

Project Configuration

Multi-Platform Project Structure

Solution Filters

Optimization and Configuration

Trimming

Native AOT

Compression

Platform-Specific Options

Windows Options

Linux Options

Continuous Integration

GitHub Actions Example

Troubleshooting

Next Steps