Overview

Noctalia v5 is a new generation of the shell, with a native runtime, refreshed UI, and a configuration model built for the current desktop experience.

Moving from v4?

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.

Expect to recreate your compositor keybinds for opening the launcher, panels, and other Noctalia commands. The good part is that v5 ships with sane defaults, so you can get started quickly and customize from there.

The v5 docs are still being built out. If you are setting up Noctalia for the first time, start with Installation, then Running Noctalia for compositor startup and keybind setup. Once the shell is installed, How configuration works explains where settings live and which file wins when the GUI and your config both set the same option.

Topics

• Installation - Package options, distro-specific commands, and manual install steps.
• Running Noctalia - Start the shell, run it from your compositor, and wire up keybinds.
• How configuration works - Config files, GUI-managed overrides, load order, and hot reload.
• Greeter installation - Install noctalia-greeter, configure greetd, and sync your login screen with Noctalia.
• Shell - Global UI scale, fonts, animations, shadows, OSD, lock screen, and keybinds.
• Hooks - Advanced event-driven automation.
• Launcher - Application search, calculator, emoji picker, and wallpaper browser.
• Control Center - Home tab, sidebar, shortcuts, and screen time.
• Bars - Top, bottom, left, and right bars, including per-monitor changes.
• Widgets - The clock, tray, volume, workspaces, media, and other things you place inside a bar.
• Dock - Optional app dock, pinned apps, running apps, and auto-hide.
• Desktop widgets - On-desktop widgets, edit mode, and state file layout.
• Wallpaper & backdrop - Wallpaper folders, automation, per-monitor choices, and overview backdrop.
• Theme - Built-in themes, wallpaper colors, and dark/light mode.
• Palette - Color roles, custom palette files, and terminal colors.
• App Theming - Generated themes for terminals, editors, browsers, and other apps.
• Services - Audio, Brightness, Calendar, Idle, Night Light, Notifications, and Weather.
• IPC - Commands for keybinds, scripts, automation, and hooks.
• Plugins - Install and configure plugins: custom bar widgets, shortcuts, and services in Luau.

---

On the Quickshell-based v4 line? See the overview and installation.