Noctalia: a Wayland desktop shell that replaces a stack of panels and daemons

The problem Noctalia solves: too many small tools

A typical Wayland desktop is assembled from parts. One program draws the bar, another launches applications, a third shows notifications, a fourth handles the lock screen, and a fifth rotates wallpapers. Each has its own configuration format, its own idea of theming, and its own release cycle. The README describes exactly this situation: a bar, a launcher, a notification daemon, a lock screen, a wallpaper tool and a settings UI stitched together.

Noctalia's answer is to be the shell layer instead. It ships bars, widgets, a dock, a launcher, a control center, notifications, wallpaper, lock screen, session actions, clipboard history, OSDs, tray integration and desktop widgets as one program. The README frames the audience as people who want a configurable Linux desktop without assembling that stack themselves, and who still want the compositor to keep doing window management.

The scope line is worth reading twice. Noctalia is not a desktop environment. Tiling, file management, removable drives, printers and screen casting are explicitly left to the compositor or to other applications. Login and greeter support lives in a separate project, Noctalia Greeter. If you want one thing that also manages windows, this is not it by design.

How Noctalia renders without Qt or GTK

Noctalia is written in C++ and built directly on Wayland and OpenGL ES. The README states there is no Qt or GTK dependency, which is the architectural decision that shapes everything else. There is no toolkit widget tree to inherit, so the UI, rendering, configuration and IPC model are designed together rather than glued on top of a foreign event loop.

Shell surfaces are created through the layer-shell protocols the compositor exposes, which is why compositor support is conditional rather than universal. Workspace integration is the second dependency: Noctalia uses compositor-native backends where they exist, or ext-workspace-v1 on compositors that implement it. The README lists current integrations as Niri, Hyprland, Sway, Scroll, Mango, Labwc, Triad and dwl, plus other compatible Wayland compositors. It also warns that other compositors may run Noctalia with reduced workspace, window, output or session-action integration depending on what protocols and IPC they expose.

Configuration is TOML with hot reload, GUI-managed overrides, theme and palette support, template application, and IPC for runtime control. The repository carries example.toml as a starting config with all defaults, and the full reference lives on the documentation site. The combination of hot reload and IPC matters for anyone who scripts their desktop: you can change the shell at runtime without restarting it.

Installing Noctalia and running it once

The README does not carry install commands. It points to the documentation site's installation page for getting started, and to BUILDING.md for source dependencies, distro-specific package commands, build modes and install layouts. PACKAGING.md holds the packaging notes: description, dependencies, install layout and Meson options. If you want a packaged build, start from the installation page; if you want to compile, BUILDING.md is the file to read before anything else.

The repository does include a justfile that wraps the Meson build. The default mode is debug, the build directory is build-debug, the install prefix defaults to /usr/local, and the C++ standard is c++23. Configuring, building and running are three separate recipes:

just configure
just build
just run

configure runs meson setup with -Dcpp_std=c++23 and -Dtests=auto, and adds -Db_lto=true for the release mode, or -Db_sanitize=address,undefined for the asan mode. build compiles the noctalia target in the build directory for the selected mode. run executes ./build-debug/noctalia.

There is also a unit test recipe. The justfile comment says it builds and runs the unit tests, enabling their targets when auto mode omits them:

just test

After that, the shell is a running process talking to your compositor. What you should see is the bar and the shell surfaces appearing on your outputs. If nothing appears, the first thing to check is whether your compositor exposes the layer-shell protocols, because that is the gate the README names.

The beta caveat and the compositor matrix

The README carries an important note: Noctalia v5 is currently in Beta. It says the core features and architecture are stabilizing, and that you may still encounter occasional configuration or behavior adjustments before the final release. The release list backs that up. The most recent three releases are all v5.0.0 beta builds, and the last push to the repository was on 2026-08-27. That is recent, but recent commits are not the same as a stable release, and the project itself is telling you the configuration surface can still move.

The second limitation is the compositor matrix. Support is conditional on protocols. Workspace integration needs either a compositor-native backend or ext-workspace-v1. Session actions, output handling and window integration depend on what the compositor exposes through IPC. On a compositor outside the listed set, Noctalia may start and draw a bar while quietly losing the parts that make a shell feel integrated. The README is explicit that this is expected, not a bug.

The third boundary is scope. Noctalia will not mount your drives, manage your printers, mirror your screen or tile your windows. Display and login greeter support is in a separate project. If your current setup relies on one of those features living inside the shell, you will keep needing the other tool.

Plugins and where the optional features live

Noctalia has a plugin system for user-installed extensions, and the README is clear about the design intent behind it: features that are useful to some users but not essential to the core shell should live there rather than in the shell itself. The examples it gives are extra bar widgets, launcher providers, desktop widgets, panels, shortcuts, background services, compositor-specific extras, hardware-specific controls and third-party service integrations.

That is a sensible split for a project that wants to stay a shell rather than become a platform for every hardware quirk. It also means the boundary between core and plugin will decide what you get out of the box. A widget for a specific laptop's fan control is not going to be a core feature; it will be a plugin, and you will install it separately.

The README does not document how plugins are distributed, versioned or discovered. It points to the documentation site for configuration and to the plugin system as the place for extensions, so anyone planning to depend on a plugin should read the docs before assuming a stable interface.

Noctalia compared with a modular stack

The alternative most people weigh against Noctalia is a modular setup: a bar like Waybar, a launcher like rofi or fuzzel, a notification daemon like mako or dunst, a lock screen like swaylock or hyprlock, and a wallpaper daemon, each configured separately. That approach wins on replaceability. If the launcher annoys you, you swap the launcher and nothing else changes. Each tool has its own maintainer and its own release cadence, and none of them can break because the others changed an internal interface.

Noctalia trades that replaceability for consistency. Theming applies across every surface because one program draws them all. There is one config format, TOML, with hot reload and IPC, instead of five. There is one process to debug instead of five. The cost is that you cannot replace the notification system without leaving the shell, and you inherit the project's beta status across all of those surfaces at once.

There is a middle path worth noting. You can run Noctalia for the surfaces it covers well on your compositor and keep a separate tool for anything it does not cover, since it explicitly does not replace window management, file management or system services. The question is whether the consistency gain on the surfaces you do use is worth running a beta shell alongside your existing tools.

Licence, packaging and the cost of tracking v5

Noctalia is MIT licensed, with the LICENSE file at the repository root. MIT is permissive: it allows use, modification and redistribution with the copyright notice and licence text preserved. That matters if you plan to package it for a distribution or vendor it into an image. For anything beyond that general statement, read LICENSE and the packaging notes yourself; this is not legal advice.

The upgrade cost is the more practical question. The README's beta note says configuration and behavior may still be adjusted before the final release, and the release history is a run of v5.0.0 beta tags. If you configure Noctalia heavily, expect to revisit that configuration across beta releases. The TOML hot reload softens the iteration loop, but it does not protect you from a key being renamed or a default changing.

For packagers, PACKAGING.md is the relevant file, covering the description, dependencies, install layout and Meson options. The justfile shows the build knobs that exist: buildtype, cpp_std, tests, LTO for release, and sanitizers for asan. If you distribute Noctalia, pinning to a specific beta tag and reading the release notes before moving is the concrete way to avoid surprise configuration changes.

Editorial conclusion

Adopt Noctalia if you run Niri, Hyprland or Sway and want one TOML-configured shell instead of a bar, launcher, notification daemon and lock screen wired together by hand, and you accept that v5 is a beta whose configuration may still shift. Skip it if you need a stable released shell, or if your compositor is not in the supported list and you rely on workspace or session actions, since those degrade without the right protocols. Verify two things first: that your compositor provides the layer-shell protocols Noctalia needs, and that a package exists for your distribution or that you can build it from source with the Meson options in BUILDING.md.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes