What Is Noctalia? The Beginner's Guide to the Toolkit-Free Wayland Shell

CodexFuse Team · 2026-11-04T14:35:15.324Z · 15 min read min read

What Is Noctalia? The Beginner's Guide to the Toolkit-Free Wayland Shell

If you have been seeing the name noctalia float through Wayland ricing threads and wondering what is noctalia, exactly — this is noctalia explained for beginners. Noctalia is a native Wayland desktop shell that gives you a polished, configurable Linux desktop — bars, dock, launcher, control center, notifications, wallpaper, lock screen — without stitching together a half-dozen separate programs. The headline is what it is built on: starting with v5, Noctalia is a native C++ shell that talks directly to Wayland and OpenGL ES, with no Qt and no GTK dependency. Everything runs from a single TOML config file. The latest release is v5.4.1, published October 29, 2026, and this guide is current as of November 4, 2026.

This guide covers what Noctalia is and what it is not, why the v4-to-v5 rewrite matters, the Noctalia Family (including the Umbriel compositor and the Greeter login screen), how to install Noctalia on the major distros, and how it differs from Quickshell — the toolkit its old version was built on.

What Is Noctalia, Exactly?

Noctalia is a native Wayland desktop shell — the visible layer of your Linux desktop that sits around your window compositor and gives you a bar, a launcher, a dock, a control center, notifications, a wallpaper manager, and a lock screen as one cohesive program. The official README defines it this way: "Noctalia is a native Wayland desktop shell for people who want a polished, configurable Linux desktop without stitching together a separate bar, launcher, notification daemon, lock screen, wallpaper tool, and settings UI."

The v5 rewrite is the whole story. Earlier versions were built on Quickshell, a Qt/QML-based shell toolkit. Noctalia v5 was rewritten from the ground up as a native C++ shell that sits directly against Wayland protocols and OpenGL ES. The README is explicit about the philosophy: "The project is built directly on Wayland and OpenGL ES with no Qt or GTK dependency, so the UI, rendering, configuration, and IPC model are designed as one cohesive shell instead of a collection of unrelated panels and scripts." In the project's early Quickshell days it carried the tagline "quiet by design" — a philosophy of minimal distractions that press coverage still cites today.

Noctalia's repository was renamed from noctalia-dev/noctalia-shell to noctalia-dev/noctalia during the v5 era. As of November 4, 2026, it has 11,819 GitHub stars and is MIT-licensed. For anyone discovering the Noctalia Wayland shell today, v5 is the version that matters — every screenshot, config snippet, and install guide written for v4 belongs to a different generation of the project.

What Does Noctalia Actually Replace?

Noctalia replaces the entire "assemble it yourself" stack that Wayland users traditionally bolt together. A bare Wayland compositor gives you window placement and input handling — and then leaves you to find a bar, a launcher, a notification daemon, a lock screen, a wallpaper tool, and scripts for volume, brightness, and network. Noctalia ships all of that as one integrated process: multi-monitor bars with configurable widgets (taskbar, workspaces, system tray, media, network, battery, brightness, weather, clipboard, custom script-backed widgets), a dock, a launcher, a control center, notification toasts and history, a wallpaper picker, OSD overlays, a lock screen, a session panel, and desktop widgets.

The launcher deserves a special mention because it is the piece most people try first. Noctalia ships its own redesigned launcher — with the old minimal layout kept as a "simple" mode — rather than making you pair the shell with a third-party one. If you want to see what a standalone Wayland launcher looks like, the kind that runs under a shell like Noctalia, our Walker beginner guide covers one that does exactly that job.

But Noctalia does not replace your compositor, and this distinction matters. Window management, tiling, input, and display handling still belong to the compositor — Hyprland, Sway, Niri, Scroll, Mango, dwl, or a stacking compositor like labwc, all of which the README lists as supported. Noctalia is the shell layer around them, not a substitute for them. It is also not a full desktop environment in the GNOME or KDE sense: there is no settings-center-for-everything, no bundled file manager or terminal, and no application suite — it is the desktop's surface, not its operating system.

What Makes Noctalia Different? The Toolkit-Free Design

The toolkit-free design is what makes Noctalia technically interesting — and it is the entire reason the v5 rewrite happened. Most Wayland shells are built on Qt or GTK, which means they inherit those toolkits' theming, startup behavior, and dependency trees. Noctalia v5 skips the toolkit layer entirely: native C++ talking to Wayland protocols, with hardware-accelerated rendering through OpenGL ES. The result is a shell whose UI, rendering, configuration, and IPC model were designed together, instead of a collection of panels and scripts that happen to coexist.

Configuration reflects the same minimalism. Everything lives in a single TOML file — "TOML configuration with hot reload, GUI-managed overrides, theme/palette support, template application, and IPC for runtime control," per the README — and edits apply with hot reload, so you see changes without restarting your session. Features that do not belong in the core do not bloat it either: "non-essential features live in plugins," and the project ships a Luau-based plugin API with a catalog the project site counts at 330 plugins.

None of this makes Noctalia the right shell for everyone. If your workflow depends on Qt/GTK ecosystem integrations, the toolkit-free choice cuts both ways — and the project is honest that it leaves niche features behind opt-in plugins and stays deliberately non-invasive with your dotfiles. But for users who want a single configurable layer instead of a Frankenstein stack, the design delivers exactly what the old tagline promised: control of a custom desktop environment with far fewer moving parts.

The v4-vs-v5 Split: Why the Version Number Matters

The v4-vs-v5 split is the single biggest source of confusion around Noctalia, so here is the short version: v4 and v5 are effectively different products that share a name. Noctalia v4 was a Quickshell-based shell (Qt/QML under the hood); Noctalia v5 is a native C++ and OpenGL ES shell. The official docs FAQ says it plainly: "Noctalia v5 is a native C++ and OpenGL ES shell launched with noctalia. The v4 line is Quickshell-based and uses qs / noctalia-qs, so v4 commands and configuration examples should not be copied into a v5 setup."

The fresh-install point deserves emphasis because it is the one that bites real users. The installation docs are verbatim: "Noctalia v5 is a fresh install, not an automatic upgrade from the Quickshell-based v4 implementation. Its package and configuration files are separate, so both versions can be installed at the same time on most distributions, but v4 settings are not migrated." Your package manager will not replace v4 with v5, and v4's JSON config does not carry over — the config file names are different. One user account of the switch on CachyOS captures the discovery: the package is now just noctalia, "no more noctalia-qs and noctalia-shell stuff."

On the version timeline: the first v5 stable (v5.0.1) landed in September 2026, and releases have shipped roughly every two weeks since — v5.3.0 arrived October 15, 2026, and the current release, v5.4.1, was published October 29, 2026. The v5.3.0 release brought the redesigned launcher (with the old layout kept as "simple" mode), per-monitor dock configuration, media-player artwork backgrounds with a visualizer and adjustable blur, and a security pass that blocked the built-in calculator from running programs or touching files while you type, and kept revealed passwords out of the clipboard and undo history. The v5.4.1 release kept the cadence going with lockscreen authentication hardening, encrypted notification history, a wallpaper filename injection fix, symbolic taskbar icons, and a Romanian translation.

What Is the Noctalia Family? (Umbriel and Greeter)

The Noctalia Family is the project's answer to the obvious next question: if Noctalia is the shell layer, what sits around it? The project's site brands itself "A Family of Native Wayland Projects," and the family has three members. Noctalia itself is the shell — "the things you reach for, all day: bar, launcher, control center, lock screen, and wallpaper-driven theming — configured in one place, on every major Wayland compositor."

Umbriel is the family's Wayland compositor, built by the same team. The official Umbriel docs describe it as "a Wayland compositor with scrolling, dwindle, master, and stacking layouts, independent workspaces per monitor, and configurable visual effects," adding that "it works on its own or with Noctalia, a desktop shell designed to integrate with Umbriel." It carries roughly 1.4K GitHub stars as of November 2026, and — like the shell — it is written in native C++ with no toolkit dependency.

Greeter is the family's graphical login screen for greetd. Per the official docs: "Noctalia Greeter is a graphical login screen for greetd. It lets you select a user and Wayland session, authenticate, and choose a color scheme using the same visual language as Noctalia." Together, the three cover the full session arc — login screen, compositor, shell — without pulling in a traditional desktop environment.

How Do You Install Noctalia?

You install Noctalia like any native Linux package — and because the project now ships official distro packages, a Noctalia install is one command on most systems. Noctalia runs on your Linux machine, the same kind of box we cover in our VPS hosting guide, and the official docs give per-distro routes verified as of November 4, 2026:

1. Pick your package route. Arch Linux: sudo pacman -S noctalia (it is in the [extra] repo — no AUR helper needed). Fedora 44 and later: sudo dnf install noctalia. Debian: add the official APT repository at pkg.noctalia.dev (the docs give the keyring install) then sudo apt install noctalia — the repo also carries noctalia-greeter, umbriel, and xdg-desktop-portal-umbriel. NixOS/Nix: the flake is github:noctalia-dev/noctalia, with Home Manager and NixOS modules plus a Cachix binary cache. Also covered: openSUSE (zypper), Gentoo (GURU overlay), GNU Guix, Chimera Linux, Solus, and Void/Alpine Edge.
2. Install the package. The Debian route is the most involved: install the keyring with wget https://pkg.noctalia.dev/deb/nickh-archive-keyring.deb && sudo dpkg -i nickh-archive-keyring.deb, add the APT sources, then sudo apt update && sudo apt install noctalia. On Arch and Fedora it is genuinely one command.
3. Launch it from your compositor's autostart. The recommended launch is noctalia at session start: Niri uses spawn-at-startup "noctalia", Umbriel takes autostart = ["noctalia"] under [general] in ~/.config/umbriel/config.toml, and Hyprland's Lua config calls hl.exec_cmd("noctalia"). There is also a daemon mode: noctalia --daemon.
4. Open the config and theme it. First launch creates the TOML config; the docs note GUI-managed overrides, theme/palette support, and template application for the parts you do not want to hand-edit.
5. Tweak live. Edits hot-reload, so you can adjust bar widgets, dock, and launcher behavior and see the result without restarting your session.

If you build from source instead, the docs prescribe git clone https://github.com/noctalia-dev/noctalia --branch main followed by just configure release, just build release, and sudo just install release (you will need the just runner and Meson); the binary lands at /usr/local/bin/noctalia. Two things to skip: do not copy v4's qs/JSON examples into a v5 setup, and do not hunt for an AUR package — the project's official Arch route is the [extra] repo package, and we could not verify any v5 AUR package this run.

What Noctalia Is Not

Noctalia is not a compositor, not a full desktop environment, and not a cross-platform app. The "not a compositor" line is worth repeating because shell and compositor get conflated constantly: your compositor (Hyprland, Sway, Niri, labwc, dwl, and the rest) still owns window placement, tiling, and input — Noctalia owns the desktop surfaces around it. If you want windows managed differently, you change the compositor, not the shell.

It is also Linux-only, by design. The README frames the audience as people who want "a polished, configurable Linux desktop," and every install route — pacman, dnf, zypper, APT, Guix, Nix — is a Linux one. There is no Windows or macOS build, and none is on the roadmap implied by the docs. And it is Wayland-only in the strong sense: the shell is built directly on Wayland protocols (layer-shell, session-lock, and compositor-specific protocols), so an X11 session is outside its design entirely.

Noctalia vs Quickshell: Which One Should You Pick?

Here is the direct answer to "noctalia vs quickshell": they are no longer competitors — they are different layers. Quickshell is a toolkit for building desktop shells (Qt/QML-based); Noctalia v5 is a finished shell that no longer uses it. Choosing Noctalia means choosing a complete, configured shell; choosing Quickshell means choosing the toolkit you would write your own shell in.

The confusion is understandable, because until recently they were the same stack: Noctalia v4 was Quickshell-based, and the old guides still floating around describe that era. Keyboard-driven users crossing over will feel at home either way — Noctalia is fully keyboard-operable, and if you want system-wide key remapping underneath it, our keyd beginner guide covers the daemon that does exactly that on Linux.

Sources

Every fact in this article comes from a source fetched on November 4, 2026:

• Noctalia GitHub repository README and metadata (native C++ design, components, compositor support, plugin system, stars and license) — https://github.com/noctalia-dev/noctalia
• Noctalia GitHub Releases API (v5.4.1, v5.4.0, v5.3.0, and v5.2.1 release dates and official release-body headlines) — https://api.github.com/repos/noctalia-dev/noctalia-shell/releases
• Official installation docs (per-distro package routes, Nix flake and modules, build-from-source commands) — https://docs.noctalia.dev/noctalia/getting-started/installation/
• Official v4-vs-v5 FAQ (launch commands, fresh-install note, config-format split) — https://docs.noctalia.dev/noctalia/getting-started/faq/
• Official "running the shell" docs (compositor autostart recipes, daemon mode) — https://docs.noctalia.dev/noctalia/getting-started/running-the-shell/
• Official NixOS docs (flake input, Home Manager and NixOS modules, Cachix cache) — https://docs.noctalia.dev/noctalia/getting-started/nixos/
• Noctalia project site (Noctalia Family branding, plugin catalog count) — https://noctalia.dev
• Official Umbriel docs (compositor features, works standalone or with Noctalia) — https://docs.noctalia.dev/umbriel/
• Official Greeter docs (greetd login screen description) — https://docs.noctalia.dev/greeter/
• LinuxCompatible, "Noctalia v5.3.0 Release: Redesigned Launcher and Security Hardening for Wayland Desktops" (v5.3.0 headlines, first-stable timing, Noctalia Family framing) — https://www.linuxcompatible.org/story/noctalia-v530-release-redesigned-launcher-and-security-hardening-for-wayland-desktops/
• LinuxCompatible, "Noctalia 5.2.1 Patch Adds Bug Fixes and Launcher Shortcuts to Wayland Shell" (v5.2.1 timing, Triad removal, palette JSON caveat, "quiet by design" tagline) — https://www.linuxcompatible.org/story/noctalia-521-patch-adds-bug-fixes-and-launcher-shortcuts-to-wayland-shell/
• Chi Señires, "Updating Noctalia v4 to v5" (real-user v4-to-v5 migration account, CachyOS) — https://chisenires.design/blog/updating-noctalia-v4-to-v5/
• dev.to, "Noctalia Shell: The Minimalist Wayland Desktop Designed for Deep Focus" (Quickshell-era historical context) — https://dev.to/githubopensource/noctalia-shell-the-minimalist-wayland-desktop-designed-for-deep-focus-oj7
• umatechnology.org, "Noctalia — minimal desktop shell for Wayland" (independent v4-era explainer) — https://umatechnology.org/noctalia-minimal-desktop-shell-for-wayland/

Frequently Asked Questions

Is Noctalia free?

Yes. Noctalia is MIT-licensed open source, so it is free to use, modify, and redistribute. The source lives on GitHub at noctalia-dev/noctalia, where it has gathered roughly 11.8K stars as of November 2026.

Can I upgrade from Noctalia v4 to v5 automatically?

No — and this is the most important practical fact in this guide. Noctalia v5 is a fresh install, not an automatic upgrade from the Quickshell-based v4 line. It ships as a separate package, your package manager will not replace v4 with v5, and v4 settings are not migrated (v4 config is JSON-only, v5 config is TOML, and the file names differ). Back up your v4 setup before installing v5.

Which compositors does Noctalia work with?

The README's current compositor integrations are Niri, Hyprland, Sway, Scroll, Mango, Labwc, dwl, and other compatible Wayland compositors. If you run one of these, Noctalia slots in as the shell layer; the team's own Umbriel compositor is the officially integrated pairing.

How do I install Noctalia on Arch Linux?

Run sudo pacman -S noctalia — the package is in Arch's [extra] repo, so no AUR helper is needed. Launch it with noctalia (or noctalia --daemon), ideally from your compositor's autostart.

Is Noctalia a full desktop environment?

No. Noctalia provides the shell layer — bars, dock, launcher, control center, notifications, wallpaper, lock screen, session actions — around your compositor, which still handles window management. It is deliberately not a GNOME/KDE-style desktop environment: no settings center for everything, no bundled apps, just the desktop's surface configured from one TOML file.