Skip to main content

Desktop Linux

How Avalonia runs on Linux​

Avalonia uses the Win32 API on Windows, its own native Objective-C++ backend on macOS, and on Linux it targets X11 by default. Most Linux distributions that support the .NET SDK and have X11, Wayland, or framebuffer capabilities will run Avalonia applications.

On Wayland desktops, Avalonia applications run through the XWayland compatibility layer by default. Starting with Avalonia 12.1.0, you can instead opt into the native Wayland backend.

Wayland​

The Avalonia.Wayland package provides a native Wayland backend. It communicates with the compositor using the Wayland protocol directly, instead of going through XWayland.

The backend supports mouse, touch, and keyboard input. It also supports clipboard and drag-and-drop. Rendering uses OpenGL or OpenGL ES through EGL, with an optional dma-buf swapchain path.

caution

The Wayland backend is experimental. UsePlatformDetect() does not select it automatically; you must enable it explicitly.

Enabling the Wayland backend​

  1. Add the Avalonia.Wayland package to your project:

    dotnet add package Avalonia.Wayland

  2. Call UseWayland() on your AppBuilder in Program.cs:

    public static AppBuilder BuildAvaloniaApp()
        => AppBuilder.Configure<App>()
            .UseWayland();

UseWayland() always initializes the Wayland backend, and there is no automatic fallback: the application will not start in an environment without a Wayland compositor. For applications that must also run on other operating systems or on X11 sessions, select the backend conditionally. For example, check the WAYLAND_DISPLAY environment variable:

public static AppBuilder BuildAvaloniaApp()
{
    var builder = AppBuilder.Configure<App>().UsePlatformDetect();

    if (OperatingSystem.IsLinux()
        && Environment.GetEnvironmentVariable("WAYLAND_DISPLAY") is not null)
    {
        builder = builder.UseWayland();
    }

    return builder;
}

Configuration options​

To configure the backend, pass a WaylandPlatformOptions instance to the AppBuilder:

public static AppBuilder BuildAvaloniaApp()
    => AppBuilder.Configure<App>()
        .UseWayland()
        .With(new WaylandPlatformOptions
        {
            UseDmabufSwapchain = true
        });
OptionDefaultDescription
WlDisplayNamenullThe Wayland display to connect to (for example, wayland-0). When null, the WAYLAND_DISPLAY environment variable is used.
EnableReconnectstrueReconnects to the compositor automatically when the connection is lost.
UseDmabufSwapchainnullUses a dma-buf-based swapchain for GPU rendering. When null, the backend decides based on compositor and driver capabilities.
GlProfilesOpenGL 4.0 down to OpenGL ES 2.0The OpenGL and OpenGL ES versions to try, in priority order, when creating the GL context.
UseGLibMainLoopfalseRuns the UI thread on a GLib main loop. Enable this when your application uses GLib-based libraries on the main thread.

Advanced options​

The following options support specialized scenarios such as compositor integration and backend testing. Typical applications do not need to set them.

OptionDefaultDescription
DisplayFdnullAn already-opened file descriptor for the Wayland display socket, used instead of connecting to a named display. When set, WlDisplayName is ignored and automatic reconnects are disabled, because libwayland consumes the file descriptor.
ForceDrawnDecorationsfalseMakes windows behave as if the compositor never advertised server-side decoration support, so client-side decorations are always used. Intended primarily for testing on compositors that otherwise enforce server-side decorations, such as KWin. Marked [Experimental]: using it requires suppressing the AVALONIA_WAYLAND_FORCE_CSD compiler diagnostic.
ExternalGLibMainLoopExceptionLoggernullReceives exceptions that would otherwise be ignored because they occur outside an Avalonia-controlled run loop frame. Only used when UseGLibMainLoop is enabled.

Current limitations​

Some KDE-specific integrations are not yet available on the Wayland backend: the global application menu, window icons, and blur-behind effects. Applications that depend on these features should continue to use the X11 backend.

WSL 2 (Windows Subsystem for Linux)​

WSL 2 is a feature of Windows that lets you run a full Linux environment directly on Windows without a traditional virtual machine or dual-boot setup. This is useful for developers who want to build and test Linux applications while staying in a Windows workflow.

Avalonia runs under WSL 2 distributions, but some libraries that are typically pre-installed on full desktop distributions need to be installed manually:

sudo apt install libice6 libsm6 libfontconfig1

Accessibility​

Avalonia exposes the accessibility tree to assistive technologies on Linux through the AT-SPI2 (Assistive Technology Service Provider Interface) protocol. This allows screen readers such as Orca to discover and interact with Avalonia controls, including announcing control names, reading text content, and tracking focus changes.

AT-SPI2 support is enabled automatically when a D-Bus session bus is available and an accessibility service is running. No additional configuration is required in your application.

Testing with Orca​

Orca is the default screen reader on most GNOME-based distributions. To verify your application's accessibility:

  1. Install Orca if not already present: 
    sudo apt install orca
  2. Enable accessibility in your desktop environment. On GNOME, open Settings > Accessibility and enable the Screen Reader toggle, or launch Orca from the terminal: 
    orca &
  3. Run your Avalonia application. Orca should announce controls as they receive focus.

Testing with Accerciser​

Accerciser is an interactive accessibility explorer that displays the AT-SPI2 tree. It is useful for verifying that your controls expose the correct roles, names, and states:

sudo apt install accerciser
accerciser &

Navigate the tree in Accerciser while interacting with your running application to inspect what information each control exposes.

For general guidance on making your application accessible, see Accessibility.

See also​

On this page