Wayland is no longer a side project on the edge of Linux. It is steadily becoming the default display system across major distributions, while X11 slips into compatibility mode through XWayland. For developers building cross-platform applications with Avalonia, that shift matters. Applications may run today, but the long-term future of Linux graphics is Wayland, and supporting it properly is not optional.
This post explains what this all means, why it's more complicated than you might think, and how we're approaching Wayland support for Avalonia.
Understanding the Linux Graphics Stack
If you're like the majority of our users, you'll have a strong background in Windows development; you're used to a relatively straightforward graphics story.
Your application talks to Win32 or WPF, which talks to Windows' compositor (DWM), which handles your windows and puts pixels on screen. Microsoft controls the entire stack. One API, one implementation, one set of behaviours.
Linux is... different.
On Linux, your application needs to talk to a display server. A separate process that manages windows, handles input, and coordinates which application draws where. For the past 40 years, that display server has been X11 (also called X or X.org).
Think of X11 as the Linux equivalent of Windows' Desktop Window Manager, except it was designed in 1984 when networked terminals were the hot new thing.
On top of this display server sits your desktop environment, GNOME, KDE, XFCE, and dozens of others. These provide the actual user interface: the taskbar, window decorations, application launcher, and all the visual polish. If the display server is the engine, the desktop environment is the car's interior and controls.
Wayland: The Modern Replacement Nobody Can Agree On
Wayland is the replacement for X11. It's been in development since 2008, which should tell you something about how easy it is to replace 40 years of accumulated functionality.
Where X11 is a massive, monolithic server that handles everything, Wayland is just a protocol. It's a set of rules for how applications should talk to the compositor.
Here's where it gets interesting (and by interesting, I mean frustrating for us developers): In Wayland, each desktop environment implements its own compositor. GNOME has Mutter, KDE has KWin, and there are standalone compositors like Sway and Wayfire. They all speak Wayland, but they each have their own interpretations, extensions, and quirks.
But if we're honest, this is just the latest chapter in a familiar Linux story. "Linux support" has never meant supporting one thing. Linux isn't an operating system like Windows or macOS; it's a kernel with hundreds of distributions built on top of it. Ubuntu, Fedora, Arch, Debian, SUSE, each with its own package managers, init systems, and desktop environments. Each distribution can be configured in countless ways. The fragmentation that makes Linux powerful, the freedom to choose and customise every layer of your system, also makes it incredibly challenging to support.
As framework developers, we can't just test against "Linux." We test against Ubuntu 22.04 with GNOME on X11, and Ubuntu 22.04 with GNOME on Wayland, and Fedora with KDE, and Arch with Sway, and the list goes on. A bug that only appears on Debian with XFCE when using a specific graphics driver isn't theoretical; it's Tuesday.
Imagine if Windows 10, Windows 11, and Windows Server each had slightly different implementations of Win32, and your framework had to abstract over all of them so your users didn't have to care. That's Wayland, except instead of three variants, there are dozens of different compositor implementations. Multiply that by hundreds of Linux distributions, and you're looking at thousands of possible combinations your framework needs to handle gracefully.
Why Wayland is Both Necessary and Painful
Now, it may sound like we're not fans of Wayland. So if that's the case, why is Wayland even a thing? The Linux community has valid reasons for pushing Wayland. X11's architecture was designed for a different era. It makes modern features incredibly difficult:
Security: In X11, any application can see all keyboard input and screenshot your entire desktop. Great for automation tools, terrible for security.
Performance: X11's architecture adds layers between applications and the display. Wayland eliminates them.
Modern Features: such as proper HiDPI scaling, which we take for granted on Windows and macOS are an architectural nightmare in X11.
But here's why developers are pulling their hair out. The Wayland protocol is intentionally minimal. Features that X11 provided, like setting window positions, system tray icons, or global hotkeys, are either missing or require compositor-specific extensions. What works in GNOME might not work in KDE. What works in both might not work in Sway. This is the part that often gets lost in the "just add Wayland support" requests. There is no single "Wayland support" to add.
Each compositor can implement its own protocol extensions for features beyond the base Wayland protocol. Need to show a system tray icon? That's the StatusNotifierItem protocol on KDE, but GNOME doesn't support it at all. Want to position a window? The core protocol doesn’t allow it. Need popup menus or tooltips to appear in the right place? The behaviour varies between compositors. Global hotkeys? Clipboard handling? Drag and drop? Each feature might require different code paths for different compositors, if they’re supported at all.
For Avalonia, this means "Wayland support" isn't one implementation, it's potentially dozens. We're not just writing a Wayland backend; we're writing a GNOME-Wayland backend, a KDE-Wayland backend, a Sway-Wayland backend, and so on. Each has its own set of capabilities, its own quirks, and its own testing requirements. And we need to degrade when features aren't available gracefully, so your application doesn't crash just because you're running on a compositor that doesn't support that particular protocol extension you need.
The Technical Reality: This Isn't a Simple Port
All this is to say that adding Wayland support isn't just a matter of swapping out some APIs. There are considerable technical hurdles to overcome.
First, there's no official C# support for libwayland (the reference implementation of the Wayland protocol). We've had to write our own bindings from scratch. During this process, we discovered race conditions in libwayland itself.
Second, the Wayland API is more limited than any other platform we support. On Windows, macOS, iOS, Android, and even X11, we have relatively similar capabilities. Wayland is the odd one out. Features you take for granted, like positioning a window at specific coordinates, simply don't exist in pure Wayland.
Third, compositor fragmentation poses a significant challenge. Some compositors want us to draw our own window decorations (title bar, close button, etc.), something we don't do on any other platform. Others provide them, but with different behaviours. Testing across all these combinations is an exponential complexity problem.
Our Strategy: Embedded First, Desktop Later
Given these challenges, we're taking a pragmatic approach. We're targeting embedded Linux systems first.
Why embedded? Because embedded Linux deployments are controlled environments. You know precisely which compositor you're running (often Weston or a custom one).
You don't need system tray icons, complex window management, or drag-and-drop between applications. The requirements are simpler and more predictable, exactly what we need to ship working Wayland support sooner rather than later.
Focusing on embedded first will let us deliver Wayland support faster, meaning we can:
Get real-world testing of our Wayland backend
Provide immediate value to users by building for embedded devices
Build a solid foundation for desktop features
Desktop support will come, but it will be gradual. We'll add compositor-specific support one at a time, starting with the most common distros.
Sustaining the Effort
Supporting Wayland isn't a one-off feature. Every compositor update, every new distribution release, every configuration change adds to the testing matrix. The thousands of permutations we described aren't a historical problem; they're an ongoing reality that demands permanent engineering commitment.
Avalonia has always been open source because we believe in the model. But supporting something as fragmented and complex as Wayland stretches the limits of what unfunded open source work can realistically deliver. The effort required, both upfront and ongoing, is substantial.
One option we're considering is dual-licensing the Wayland backend when it ships: open source under AGPL, with commercial licensing available through Avalonia Accelerate. This would keep the technology available to the community while giving organisations that rely on Avalonia professionally a clear path to support its development.
Nothing is decided, but we want to be transparent about our thinking. Delivering quality Wayland support that works across the majority of Linux distributions requires significant investment. A sustainable model ensures Avalonia can maintain that support at the level of quality you expect, not just at launch but for years to come.
What This Means for You Today
If you're deploying Avalonia applications on Linux desktops today, you don't need to panic.
There's a technology called XWayland that acts as a compatibility layer, running X11 applications on Wayland systems. It's installed by default on virtually every desktop Linux distribution.
Think of XWayland like Windows' compatibility mode, your application thinks it's talking to X11, but behind the scenes, XWayland is translating those calls to Wayland. You might miss out on some Wayland-specific benefits (like better HiDPI scaling or reduced latency), but your application will run.
This means your existing Avalonia applications will continue to work on modern Linux distributions, whether they use X11 or Wayland. You don't need to wait for our Wayland support to deploy on the latest Ubuntu or Fedora.
The Road Ahead
Supporting Wayland isn't just a checkbox feature for us. It represents a fundamental shift in how Linux handles graphics, and we need to get it right.
The embedded-first approach lets us deliver working Wayland support sooner while we tackle the complexity of desktop compositors.
We know this might seem like a lot of complexity for what sounds like a simple feature request. But that's the reality of cross-platform development; sometimes, supporting a new platform means navigating an entirely different philosophy of how software should work.
The good news is that you don't need to understand any of this complexity. We're handling it so you don't have to. When Wayland support lands in Avalonia, it will just be another target that works, hiding all this complexity behind the same familiar API you're already using.
In the meantime, XWayland has you covered, and we're working hard to bring you native Wayland support that actually works in the real world, not just in demos.
