Noctalia Shell: Complete Guide, Installation and Configuration

Noctalia is a desktop shell for Wayland that just went through one of the most dramatic rewrites in the Hyprland/Niri ricing scene: it dropped Qt and Quickshell entirely and rebuilt itself as a native C++ and OpenGL ES application. It has 10.9k GitHub stars, and in the space of about two and a half months it went from "early alpha" to being packaged in the official repositories of Arch, Fedora, openSUSE, Gentoo and Debian/Ubuntu.

This guide covers what Noctalia actually is, what changed between the old Quickshell-based v4 and the current native v5, every real installation method by distro, how its TOML configuration system works, and an honest comparison against Caelestia Shell and the other options you'll see mentioned in the same threads.

What Is Noctalia?

Noctalia is a native Wayland desktop shell that provides the layer most Linux ricers stitch together by hand: a status bar, launcher, dock, notification daemon, lock screen, wallpaper picker, control center, on-screen displays, clipboard history and desktop widgets, all as one cohesive application instead of a pile of separate tools with separate config formats.

The project is MIT licensed, sits at 10,912 stars and 831 forks on GitHub, and the repository has had commits landing the same day this guide was written, this is an actively maintained project, not an abandoned rice. It explicitly scopes itself as a shell, not a full desktop environment: window management, tiling, monitor arrangement, file management and printer setup stay with your compositor or dedicated apps. A separate project, Noctalia Greeter, covers the login screen if you want one.

Noctalia v5: Why It Dropped Quickshell and Qt Entirely

Noctalia didn't start this way. The original version, now called the v4 "legacy" line, was built on Quickshell, the same Qt6/QML framework Caelestia Shell still uses. Noctalia v5 is a full rewrite: hand-written C++ rendering directly on OpenGL ES, no Qt or GTK dependency anywhere in the stack, and configuration moved from JSON to TOML.

The project's own FAQ is direct about the split: "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." The two can run side by side, but they're launched differently, v5 starts with the noctalia command, while v4 uses qs or noctalia-qs. Mixing v4 instructions with a v5 install, or the other way around, is the most common source of confusion in the wild right now.

What makes this worth tracking closely is the pace. As of July 2026, independent coverage described v5 as "early alpha" with "config-breaking changes still expected between alphas." Less than three months later, at the time of this guide, noctalia is in Arch's official [extra] repository (no AUR needed), Fedora's official repos from Fedora 44 onward, and has packages for openSUSE, Gentoo and Debian/Ubuntu. That's an unusually fast graduation from alpha to being trusted enough for multiple distros to package it directly.

Compositor Support: Niri, Hyprland, Sway and More

Unlike Caelestia, which only runs on Hyprland, Noctalia is compositor-agnostic by design, it works with anything that exposes the layer-shell protocols it needs.

Workspace integration specifically goes through either a compositor-native backend or the generic ext-workspace-v1 protocol on compositors that support it. That's why the "native integration" list above is longer than Caelestia's Hyprland-only scope, but also why a compositor outside that list isn't automatically a safe bet, check what protocols it actually implements before assuming full functionality.

In practice, the two pairings that show up most in real search behavior are Niri and Hyprland, in roughly that order of association with Noctalia specifically. That tracks with why the project exists at all: Niri in particular has no equivalent to Waybar's ecosystem of maturity, so a single shell that already speaks its workspace protocol natively fills a gap Hyprland users don't feel as strongly, since Hyprland already has Caelestia, End-4, HyprPanel and the classic Waybar stack to choose from.

Requirements Before You Install

Noctalia is officially packaged for Arch Linux, NixOS, Fedora and openSUSE, per the project's own FAQ, plus community packages for Gentoo and Debian/Ubuntu covered below. Manual installation is possible on other distros if you can satisfy the build and runtime dependencies yourself.

Build dependencies (Arch package names, adjust for your distro): meson, gcc, just, wayland, wayland-protocols, libglvnd, freetype2, fontconfig, cairo, pango, harfbuzz, libxkbcommon, glib2, libsecret, libsodium, sdbus-cpp, libpipewire, wireplumber, polkit, pam, curl, libwebp, libjxl, libsndfile, librsvg, libqalculate, libxml2, md4c, tomlplusplus, nlohmann-json, stb, jemalloc.

That's a genuinely long dependency list, PipeWire, WirePlumber, PAM, polkit and several image/font libraries are all pulled in directly rather than through Qt, since Noctalia now implements its own rendering and media handling instead of leaning on a framework for it. In exchange, you get a shell with no Qt runtime to carry, which matters if you were avoiding Quickshell specifically for that reason.

If you're installing from an official package (Arch, Fedora, openSUSE, Debian/Ubuntu, NixOS), your package manager resolves all of this for you, you never see the list above at all. It only becomes relevant if you're building manually on a distro without a package, or packaging Noctalia yourself for one that doesn't have it yet.

How to Install Noctalia

Real, official commands per distro, also kept current on the official installation page:

Arch Linux

sudo pacman -S noctalia

It's in the [extra] repository directly, no AUR helper required.

Fedora

Official repo, Fedora 44 and newer:

sudo dnf install noctalia

Or the development snapshots via Copr:

sudo dnf copr enable lionheartp/Hyprland
sudo dnf install noctalia-git

openSUSE

Tumbleweed:

sudo zypper addrepo --refresh --name noctalia-v5 https://download.opensuse.org/repositories/home:neifua:Noctalia/openSUSE_Tumbleweed/home:neifua:Noctalia.repo
sudo zypper refresh
sudo zypper install noctalia

Slowroll uses the same pattern with openSUSE_Slowroll in the URL instead.

Gentoo

emerge --ask gui-apps/noctalia

Requires enabling the GURU overlay and unmasking the package first.

Debian / Ubuntu

wget https://pkg.noctalia.dev/deb/nickh-archive-keyring.deb && sudo dpkg -i nickh-archive-keyring.deb
sudo wget -O /etc/apt/sources.list.d/noctalia-trixie.sources https://pkg.noctalia.dev/deb/noctalia-trixie.sources
sudo apt update
sudo apt install noctalia

NixOS

Officially packaged, install through your normal flake or channel workflow the same way you would any other Nix package, see our NixOS flakes guide if you're setting up a system from scratch.

Manual build from source

git clone https://github.com/noctalia-dev/noctalia --branch main
cd noctalia
just configure release
just build release
sudo just install release

Distro-specific dependency commands and install layout options live in the project's BUILDING.md and PACKAGING.md files if you need to adapt this for a distro not listed above.

Starting Noctalia and Compositor Integration

Start it manually with:

noctalia

Or run it detached so it doesn't die when you close the terminal that launched it:

noctalia --daemon

Noctalia doesn't manage session autostart itself, its own FAQ is explicit about that: "Noctalia does not manage session autostart from its Settings app. Use your compositor's autostart mechanism instead." That means you add it to your compositor's own startup config:

• Hyprland (classic hyprland.conf): add exec-once = noctalia to your config.
• Hyprland (newer Lua config, hyprland.lua): Hyprland 0.55 introduced Lua as the config format going forward, and exec-once has no direct Lua equivalent, you subscribe to the startup event instead: hl.on("hyprland.start", function() hl.exec_cmd("noctalia") end). If you don't have a hyprland.lua file, your existing hyprland.conf still loads normally, you don't need to migrate just to run Noctalia.
• Niri: add spawn-at-startup "noctalia" to the end of ~/.config/niri/config.kdl.

How to Configure Noctalia

Configuration is genuinely more structured than most Hyprland shells, and it's split across two files with different purposes:

• ~/.config/noctalia/config.toml: your manually-edited config. Copy the project's example.toml as a starting point, it ships with every setting at its default, commented, so you only need to touch what you want to change. Most changes hot-reload via inotify, the file is watched and applied live, no restart needed for most settings.
• ~/.local/state/noctalia/settings.toml: written automatically by the Settings app when you change something through the GUI instead of editing TOML by hand. The project's FAQ is clear on this split: "If you only use Settings, you normally do not need to edit config files."

The config is organized into real top-level TOML sections, not a flat list of options:

The [keybinds] section is worth calling out specifically because it's easy to misread: it only covers keys used while interacting with Noctalia's own panels (confirming a selection, cancelling a dialog, arrow-key navigation), it is not where you set global shortcuts to open the launcher or lock the screen, those still live in your compositor's config and get wired up to Noctalia's IPC commands.

Settings app or hand-edited TOML, pick one workflow and stick to it. Both routes end up changing the same underlying values, but they write to different files, and mixing them without understanding the split is how people end up confused about why a setting "keeps resetting." If you're new to Noctalia, start entirely in the Settings app until you hit something it doesn't expose, then drop into config.toml for that specific value instead of moving your whole config to hand-editing on day one. Caelestia doesn't have this two-file split at all, everything there lives in one shell.json you edit directly, so this is a genuine workflow difference between the two shells, not just a syntax one.

The bar layout is genuinely readable. [bar.main] defines what's on the bar as three plain arrays:

start  = ["launcher", "wallpaper", "workspaces"]
center = ["clock"]
end    = ["media", "tray", "notifications", "clipboard", "network", "bluetooth", "volume", "brightness", "battery", "control-center", "session"]

Reordering the bar is reordering a list, not editing markup. Per-monitor overrides work the same way as the global settings, just scoped: [bar.main.monitor.dp1] with a match field to identify the output, and only the fields you list there override the global config for that monitor.

Updating Noctalia

Update method follows however you installed it: sudo pacman -Syu on Arch, sudo dnf upgrade on Fedora, sudo zypper update on openSUSE, sudo apt update && sudo apt upgrade on Debian/Ubuntu, or pulling the latest commit and re-running the just build steps if you compiled manually. Because v5 is moving fast, more so than most Hyprland shells at this point, checking release notes before a major update is worth the extra minute, the project itself warns about config-breaking changes between versions while it's still this young.

Theming, App Templates and the Plugin System

Noctalia generates a color palette and can push it out to other applications through templates, official templates exist for GTK and Qt apps, plus community templates for tools like Emacs, VS Code, Discord and Firefox, so your terminal, editor and browser can pick up the same palette instead of staying visually disconnected from the shell.

Beyond theming, there's a real plugin system for extending the shell itself, separate from the core: extra bar widgets, launcher providers, desktop widgets, panels, background services and hardware- or compositor-specific controls. The project deliberately keeps this kind of thing out of core Noctalia and in the plugin layer instead, which is part of why the core stays comparatively lean despite doing more than Caelestia out of the box.

This isn't a theoretical extension point, there's already a real community ecosystem building on it. Examples that exist today: an Alertmanager plugin for surfacing Prometheus alerts directly in the shell, a Nostr chat client plugin, a display-configuration plugin, a Lenovo Vantage control plugin for Lenovo laptop hardware features, an Android-device plugin built on top of KDE Connect with embedded scrcpy screen mirroring, and an advanced clipboard manager plugin that goes beyond the built-in clipboard history. None of that had to become core Noctalia code to exist, which is the point of keeping the plugin layer separate.

Noctalia vs Other Wayland Shells

The practical split: if you want the broadest compositor support and a shell that doesn't depend on Qt at all, Noctalia is currently the strongest option, and it's the only one of these that runs natively on Niri, Sway and several other compositors beyond Hyprland. If you're specifically on Hyprland and want the most mature, most documented QML-based option, Caelestia has the longer track record. If you just want the lightest possible setup and don't mind separate configs, the Waybar stack still wins on resource use.

Is Noctalia Worth Installing Right Now?

Yes, with a timing caveat worth being honest about. The speed of the v4-to-v5 transition, alpha in July, official Arch and Fedora packages by late September, is a genuinely good sign for the project's momentum, but it also means v5 is young. 542 open issues on a repository with under 11,000 stars is a real, active bug count, not necessarily unusual for a project moving this fast, but worth knowing before you commit a daily-driver setup to it.

If you're on Niri or Sway and want a full-featured shell, Noctalia is close to the only serious option right now, most competing shells are Hyprland-only. If you're on Hyprland specifically and want the safest bet, weigh Noctalia's broader official packaging against Caelestia's longer history on that one compositor. Either way, the fact that your distro's package manager now offers noctalia directly, on five separate distros, is the strongest signal that this isn't a fringe project anymore.

One practical decision point that doesn't show up in feature comparisons: if you're still running v4 anywhere, don't assume upgrading your distro package pulls you onto v5 automatically. It won't, they're separate packages by design, and your existing v4 config and compositor integration lines will keep working untouched until you deliberately install v5 alongside or instead of it. That's a safer default than most rewrites give you, but it also means nobody's config silently breaks on a routine update, which is worth knowing if you maintain multiple machines.

Troubleshooting Noctalia: Common Problems and Questions

What is Noctalia?

Noctalia is a native Wayland desktop shell providing a bar, launcher, dock, notifications, lock screen, wallpaper picker, control center and clipboard history as one application, built directly on Wayland and OpenGL ES with no Qt or GTK dependency.

What's the difference between Noctalia v4 and v5?

v4 was built on Quickshell (Qt6/QML) and is now the legacy line, launched with the qs or noctalia-qs command. v5 is a full rewrite in native C++ and OpenGL ES with TOML configuration, launched with the noctalia command. There is no automatic upgrade between them, v5 is a fresh install and ships as a separate package.

Can I keep both v4 and v5 installed?

Yes, they ship as separate packages and your package manager will not replace one with the other. Just be aware their config files, commands and compositor integration lines are different, don't mix instructions between them.

Which distros officially package Noctalia?

Arch Linux (official extra repo, no AUR needed), NixOS, Fedora (44 and newer), and openSUSE are officially packaged per the project's own FAQ. Community packages also exist for Gentoo and Debian/Ubuntu.

Does Noctalia work on Niri, or only Hyprland?

Both, and more. Native integrations exist for Niri, Hyprland, Sway, Scroll, Mango, Labwc, Triad and dwl. Other Wayland compositors may run it with reduced workspace or session integration depending on which protocols they support.

How do I start Noctalia automatically?

Noctalia does not manage session autostart itself, add it to your compositor's own startup mechanism: exec-once = noctalia in a classic hyprland.conf, the hl.on("hyprland.start", ...) event hook in a Lua hyprland.lua config, or spawn-at-startup "noctalia" in Niri's config.kdl.

Where do I put my configuration?

Manual edits go in ~/.config/noctalia/config.toml, copied from the project's example.toml. If you only use the Settings app instead of editing TOML by hand, your changes are written automatically to ~/.local/state/noctalia/settings.toml, and you normally never need to touch config.toml at all.

Why does my keyboard shortcut not work?

Check three things in order: Noctalia is actually running, you're using v5 IPC commands in the form noctalia msg ... and not leftover v4 syntax, and your compositor's own bind syntax pointing to that command is correct.

Why is my battery widget missing?

Battery status comes from UPower. Make sure UPower is installed and actually running on your system.

Why doesn't an app show up in the launcher or dock?

Noctalia discovers applications from .desktop files in the standard application directories, if an app didn't install a proper .desktop entry, it won't be discoverable.

Why don't weather or night light work?

Both features depend on Settings → Location being configured first, either with Auto locate or a manually entered address. Without a location set, neither has the data it needs.

Why can't I unlock my lock screen?

Noctalia authenticates through PAM using the login service. Confirm /etc/pam.d/login exists and is valid for your distribution, a missing or broken PAM service file is the usual cause.

How do I make the interface bigger or smaller?

Use your compositor's own output scaling for HiDPI monitors. That's the officially recommended approach and it affects all Wayland clients consistently, not just Noctalia.

Can I use a different wallpaper tool with Noctalia?

Yes. If you already manage wallpapers with something like waypaper, swww or hyprpaper, let that tool draw the wallpaper and let Noctalia use the image only for its color extraction, you don't have to give up your existing wallpaper setup.

Why do two copies of the same widget share settings?

Widget settings are attached to the widget's name as it appears in the bar list. Placing the same widget name twice means both entries share one configuration, they're not independent instances.

Can I choose Monday instead of Sunday as the first day of the week?

Not as a Noctalia setting, there's no Settings toggle or TOML key for it in v5. Noctalia follows your system locale for this instead.

Why can't NetworkManager talk to wpa_supplicant?

This is usually a D-Bus permissions problem or an incorrect service option in your NetworkManager setup rather than anything Noctalia itself controls, check your wireless management configuration outside the shell first.

Why can't I connect to my VPN from the network widget?

By default NetworkManager generates VPN connections scoped to the current user only, and saves secrets through nm-applet. If the VPN was set up under a different user or without nm-applet handling the secrets, the network widget won't be able to connect either.

How do I change Noctalia's display language?

Noctalia follows your system locale by default. To override it, go to Settings, Appearance, Interface, Language.

Does Noctalia support touchscreens?

Yes. Tapping works normally, and in scrollable views you can drag vertically over rows, buttons or other controls to scroll, including a fling gesture on a fast release.

Further Reading

• Caelestia Shell: Complete Guide, Installation and Configuration
• CachyOS: Install and Configure the Performance-Tuned Arch Linux Distro
• How to Install NixOS in 2026: The Flakes-First Way