Skip to main content
Avalonia provides comprehensive support for building desktop applications on Windows, macOS, and Linux with a single codebase.

Platform Detection

The easiest way to support all desktop platforms is using automatic detection:
using Avalonia;
using Avalonia.Controls.ApplicationLifetimes;

class Program
{
    public static void Main(string[] args)
    {
        BuildAvaloniaApp()
            .StartWithClassicDesktopLifetime(args);
    }

    public static AppBuilder BuildAvaloniaApp()
        => AppBuilder.Configure<App>()
            .UsePlatformDetect()  // Automatically selects platform
            .LogToTrace();
}
Source: src/Avalonia.Desktop/AppBuilderDesktopExtensions.cs:8

Windows Support

Platform Implementation

Avalonia’s Windows support is based on the Win32 API:
  • Backend: Avalonia.Win32
  • Rendering: Skia + Direct2D
  • Minimum Version: Windows 7 or later
  • Architecture: x86, x64, ARM64

Configuration

AppBuilder.Configure<App>()
    .UsePlatformDetect()  // Detects Windows automatically
    .StartWithClassicDesktopLifetime(args);

Windows Platform Options

using Avalonia.Win32;

AppBuilder.Configure<App>()
    .With(new Win32PlatformOptions
    {
        // Render on UI thread (default: false)
        ShouldRenderOnUIThread = false,
        
        // Use overlay popups (default: true)
        OverlayPopups = true,
        
        // Enable Windows composition APIs
        UseWgl = false,
        
        // DPI awareness
        RenderingMode = new[]
        {
            Win32RenderingMode.Wgl,
            Win32RenderingMode.Software
        }
    })
    .UseWin32()
    .UseSkia();

Windows Features

  • DPI Awareness: Automatic per-monitor DPI scaling
  • Window Composition: DirectComposition and WinUI Composition
  • Native Menus: Windows menu bar support
  • System Tray: Notification area icons
  • Jump Lists: Taskbar jump list support
  • File Dialogs: Native Windows file pickers
  • Drag & Drop: Full Windows drag-drop support
  • IME Support: Input Method Editor for Asian languages
Source: src/Windows/Avalonia.Win32/Win32Platform.cs:27

macOS Support

Platform Implementation

Avalonia’s macOS support uses the native AppKit framework:
  • Backend: Avalonia.Native
  • Rendering: Skia + Metal
  • Minimum Version: macOS 10.13 (High Sierra) or later
  • Architecture: x64, ARM64 (Apple Silicon)

Configuration

AppBuilder.Configure<App>()
    .UsePlatformDetect()  // Detects macOS automatically
    .StartWithClassicDesktopLifetime(args);

macOS Features

  • Native Look: Integrates with macOS appearance
  • Menu Bar: Native macOS menu bar (File, Edit, etc.)
  • Dark Mode: Automatic light/dark theme support
  • Retina Display: HiDPI display support
  • Mission Control: Full-screen and window management
  • System Dialogs: Native file pickers and alerts
  • Dock Integration: Application dock icon and menus
  • Metal Rendering: Hardware-accelerated graphics
Source: src/Avalonia.Native/AvaloniaNativePlatformExtensions.cs:11

Linux Support

Platform Implementation

Avalonia supports Linux through X11 and Wayland:
  • Backend: Avalonia.X11 and Avalonia.FreeDesktop
  • Rendering: Skia + OpenGL
  • Desktop Environments: GNOME, KDE, XFCE, etc.
  • Display Servers: X11 and Wayland

Configuration

AppBuilder.Configure<App>()
    .UsePlatformDetect()  // Detects Linux automatically
    .StartWithClassicDesktopLifetime(args);

Linux Features

  • X11 Support: Full X11 windowing system integration
  • Wayland Support: Experimental Wayland support
  • DBus Integration: System integration via DBus
  • GTK Dialogs: Native file picker integration
  • Freedesktop Standards: XDG desktop integration
  • Accessibility: AT-SPI accessibility support
  • IME Support: Multiple input method frameworks
  • System Tray: StatusNotifier/AppIndicator support
Source: src/Avalonia.X11/X11Platform.cs:516

Desktop Application Lifetime

Use ClassicDesktopStyleApplicationLifetime for desktop apps:
using Avalonia.Controls.ApplicationLifetimes;

public override void OnFrameworkInitializationCompleted()
{
    if (ApplicationLifetime is IClassicDesktopStyleApplicationLifetime desktop)
    {
        desktop.MainWindow = new MainWindow();
        
        // Configure shutdown mode
        desktop.ShutdownMode = ShutdownMode.OnMainWindowClose;
        
        // Handle application exit
        desktop.Exit += (sender, args) =>
        {
            // Cleanup code
        };
    }

    base.OnFrameworkInitializationCompleted();
}

Window Management

Desktop platforms support full window management:
using Avalonia.Controls;

public class MainWindow : Window
{
    public MainWindow()
    {
        Title = "My Application";
        Width = 800;
        Height = 600;
        
        // Window state
        WindowState = WindowState.Normal;
        WindowStartupLocation = WindowStartupLocation.CenterScreen;
        
        // Window features
        CanResize = true;
        ShowInTaskbar = true;
        SystemDecorations = SystemDecorations.Full;
        
        // Transparency (platform-dependent)
        TransparencyLevelHint = WindowTransparencyLevel.AcrylicBlur;
    }
}

Native Menus

Create native menu bars on desktop platforms:
using Avalonia.Controls;

var menu = new NativeMenu();
var fileMenu = new NativeMenuItem("File");
fileMenu.Menu = new NativeMenu
{
    new NativeMenuItem("Open...") { Command = OpenCommand },
    new NativeMenuItem("Save") { Command = SaveCommand },
    new NativeMenuItemSeparator(),
    new NativeMenuItem("Exit") { Command = ExitCommand }
};
menu.Add(fileMenu);

NativeMenu.SetMenu(this, menu);

System Tray

Add system tray/notification area icons:
using Avalonia.Controls;

var trayIcon = new TrayIcon
{
    Icon = new WindowIcon("/Assets/icon.ico"),
    ToolTipText = "My Application",
    Menu = new NativeMenu
    {
        new NativeMenuItem("Show") { Command = ShowCommand },
        new NativeMenuItemSeparator(),
        new NativeMenuItem("Exit") { Command = ExitCommand }
    }
};

trayIcon.Clicked += (s, e) => ShowMainWindow();
TrayIcon.SetIcons(Application.Current, new[] { trayIcon });

File System Access

Use the Storage API for cross-platform file access:
using Avalonia.Platform.Storage;

public async Task OpenFileAsync()
{
    var topLevel = TopLevel.GetTopLevel(this);
    var files = await topLevel.StorageProvider.OpenFilePickerAsync(
        new FilePickerOpenOptions
        {
            Title = "Select a file",
            AllowMultiple = false,
            FileTypeFilter = new[]
            {
                new FilePickerFileType("Text Files")
                {
                    Patterns = new[] { "*.txt" },
                    MimeTypes = new[] { "text/plain" }
                }
            }
        });
    
    if (files.Count > 0)
    {
        await using var stream = await files[0].OpenReadAsync();
        // Process file
    }
}

Platform-Specific Code

Detect and handle platform-specific behavior:
using System.Runtime.InteropServices;

if (RuntimeInformation.IsOSPlatform(OSPlatform.Windows))
{
    // Windows-specific code
}
else if (RuntimeInformation.IsOSPlatform(OSPlatform.OSX))
{
    // macOS-specific code
}
else if (RuntimeInformation.IsOSPlatform(OSPlatform.Linux))
{
    // Linux-specific code
}

Performance Optimization

Rendering Options

Optimize rendering for desktop platforms:
// Enable GPU acceleration
AppBuilder.Configure<App>()
    .UseSkia()
    .With(new SkiaOptions
    {
        // Use GPU rendering when available
        CustomGpuFactory = null,
        
        // Maximum FPS
        MaxFrameRate = 60
    });

Memory Management

Desktop platforms have more memory available:
// Configure for desktop memory profile
AvaloniaLocator.CurrentMutable
    .Bind<IPlatformSettings>()
    .ToConstant(new DefaultPlatformSettings
    {
        // Desktop defaults
    });

Deployment

Windows Deployment

  • Standalone EXE: Self-contained or framework-dependent
  • Installer: MSI, MSIX, or third-party installers
  • ClickOnce: Web-deployed applications

macOS Deployment

  • Application Bundle: .app bundle
  • DMG: Disk image for distribution
  • App Store: Mac App Store deployment
  • Code Signing: Required for macOS 10.15+

Linux Deployment

  • AppImage: Portable application format
  • Snap: Universal Linux package
  • Flatpak: Sandboxed application
  • DEB/RPM: Distribution-specific packages

Next Steps

Platform-Specific Features

Access native desktop APIs

Mobile Platforms

Build for iOS and Android

Build docs developers (and LLMs) love