Skip to content
Get packs

Guide · Open source

How to use Noctalia: install, configure and customize it

Updated · written with AI from the project's own documentation and checked against our catalogue data

Noctalia is a desktop shell for Linux that runs on Wayland. It supplies the visual layer around a compositor such as Niri, Hyprland or Sway, combining a bar, launcher, notifications, wallpaper picker and lock screen in one configurable program. This guide explains what you need before you start, how to get the source, where the configuration lives and how to adjust it.

Noctalianoctalia-dev/noctalia · ★ 11.8k · MIT

Quick start

  1. 1Confirm you run Wayland. Check that your session uses a Wayland compositor such as Niri, Hyprland or Sway. Noctalia is not built for X11.
  2. 2Clone the repository. Run git clone https://github.com/noctalia-dev/noctalia to get the source code.
  3. 3Read the build guide. Open BUILDING.md in the repository for source dependencies, build modes and install layouts.
  4. 4Build and install. Follow the build instructions in BUILDING.md, or the installation page at docs.noctalia.dev, for your distribution.
  5. 5Copy the example config. Start from example.toml, which includes all defaults, and adjust the settings you want to change.
  6. 6Adjust and reload. Edit the TOML file. The README says configuration supports hot reload, so changes can be applied without a full restart.

Check the requirements before you start

Noctalia needs a Wayland compositor. The project lists Niri, Hyprland and Sway as examples, and its README describes Noctalia as built directly on Wayland and OpenGL ES. It is not designed for X11.

Noctalia is a shell, not a full desktop environment. Window management and compositor configuration stay with your compositor.

  • A Wayland compositor that supports the layer-shell protocols Noctalia uses
  • Comfort editing configuration files and reading documentation

Install Noctalia by cloning and building from source

The README's install path starts by cloning the repository. Source dependencies, distro-specific package commands, build modes and install layouts are described in the project's BUILDING.md file, so read that before compiling.

The full installation guide is on the documentation site at docs.noctalia.dev.

  • Read BUILDING.md for dependencies and build modes
  • Packaging notes for distributions are in PACKAGING.md
git clone https://github.com/noctalia-dev/noctalia

Understand the configuration files

Noctalia is configured with TOML. The repository includes example.toml, a ready-to-use starting config with all defaults. Copy it as a reference and change only the settings you need.

The full configuration reference is on the documentation site. Source MDX files are in docs/user/, and the README says you can sync them to a local docs checkout with tools/sync-docs.sh.

  • example.toml: starting config with all defaults
  • docs/user/: source documentation files
  • Hot reload: the README says configuration changes can be applied without restarting

Customize the bar, widgets and look

Noctalia's bars support multiple monitors and configurable widgets. The README lists widgets including taskbar, workspaces, system tray, media, network, battery, brightness, weather, clipboard and custom script-backed widgets.

Themes and palettes are supported, and the project also has GUI-managed overrides and template application. Use one palette across the bar, launcher and notifications to keep the desktop visually consistent.

  • Multi-monitor bars with configurable widgets
  • Theme and palette support
  • Custom script-backed widgets

Use the shell features day to day

Noctalia bundles a dock, app launcher, control center, notification toasts and history, wallpaper picker, OSD overlays, lock screen, session panel and desktop widgets. It also includes clipboard history and tray integration.

IPC is available for runtime control, so you can trigger shell actions from your compositor keybindings or scripts.

  • Launcher, control center and notifications
  • Wallpaper picker and lock screen
  • Session actions and clipboard history

Get help and contribute

For general help and design discussion, the README points to the Discord community. Developer notes, testing and debugging commands are in CONTRIBUTING.md, and the architecture is described in ARCHITECTURE.md.

Bug reports, fixes, documentation updates, themes and configuration examples are welcome.

  • Discord: discord.noctalia.dev
  • CONTRIBUTING.md for developer notes
  • ARCHITECTURE.md for design invariants

What people use it for

  • Running a consistent bar, launcher and notification style on a Niri or Hyprland desktop
  • Replacing separate bar, launcher, notification daemon and lock screen tools with one shell
  • Adding custom script-backed widgets to a multi-monitor bar
  • Sharing TOML configs and themes with other users in the community

Frequently asked questions

Is Noctalia free?

Noctalia is released under the MIT License, as stated in the README and LICENSE file. Donations are optional and the README describes them as completely optional.

What do I need to run Noctalia?

You need a Wayland compositor that provides the layer-shell protocols Noctalia uses. The README gives Niri, Hyprland, Sway, Scroll, Mango, Labwc and dwl as examples of supported compositors.

Does Noctalia work on X11?

The README describes Noctalia as built directly on Wayland, so it is not intended for X11 or for users who do not run a Wayland compositor.

Is Noctalia a full desktop environment?

No. The README says it is a desktop shell, not a full desktop environment. Window management and compositor configuration belong to your compositor.

How does Noctalia compare to Waybar, EWW, Quickshell or AGS?

Waybar, EWW, Quickshell and AGS are comparable projects. Noctalia's README stresses that it bundles the bar, launcher, notifications, lock screen and wallpaper tool into one shell with one config format, rather than separate tools.

Where do I find the full configuration options?

The full configuration reference is on the documentation site at docs.noctalia.dev. The repository also includes example.toml with all defaults.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Noctalia suits Linux users on a Wayland compositor who want a complete, consistent shell and are comfortable editing TOML and reading documentation. If you use X11, want a full desktop environment, or need a setup that works with no configuration, pick another option.

Install options & downloads