Installation

Moving from v4?

Noctalia v5 is a fresh install, not an automatic upgrade from the Quickshell-based v4 line. There is no in-place migration path for v4 settings, but you do not have to retire v4 to try v5.

On most distributions, v4 and v5 can be installed at the same time, and you can run whichever version you want. The packages do not conflict with each other, and Noctalia’s configuration files do not conflict either: v4 config is JSON-only, v5 config is TOML, and their config file names are different.

Only your compositor keybinds need attention. Keybinds live in your compositor config, so update the bindings that launch the Noctalia launcher, panels, settings UI, or other commands when switching between v4 and v5.

Choose your package source carefully

The Noctalia team maintains only the Arch Linux/AUR packages and the manual installation method. Packages shipped in a distribution’s official repositories, such as Fedora’s official package, are built and reviewed under that distribution’s own packaging process.

All other packages and third-party repositories listed here are maintained independently by community members in good faith. The Noctalia team does not build, audit, or control those packaged binaries and cannot guarantee their integrity. Before installing one, review its source, maintainer, and repository, and decide whether you trust it. A listing on this page is not an endorsement or a security guarantee.

Noctalia v5 is available on the following distributions:

• Arch Linux
• NixOS
• Fedora
• openSUSE
• Gentoo
• Void Linux
• GNU Guix
• Debian (including Ubuntu)

You can also install manually on any other Linux distribution.

Arch Linux

Using AUR (Recommended)

The simplest way to install Noctalia on Arch Linux is through the Arch User Repository (AUR). This method installs the shell system-wide and handles dependencies automatically.

AUR Helper

Please replace with your AUR helper of choice.

paru -S noctalia-git

Non-AUR Helper

git clone https://aur.archlinux.org/noctalia-git
cd noctalia-git
makepkg -is

---

Fedora

Noctalia is available from the default repos for Fedora 44 and up.

Step 1: Install noctalia

sudo dnf install noctalia

An alternate version using git snapshots is available from the LionHeartP Copr repository.

Step 1: Enable the repository

sudo dnf copr enable lionheartp/Hyprland

Step 2: Install noctalia

sudo dnf install noctalia-git

---

openSUSE

Noctalia is available via home:neifua:Noctalia repository on the openSUSE Build Service.

Step 1: Add the OBS repository

Tumbleweed

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

Slowroll

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

Step 2: Refresh and install noctalia:

Stable (recommended)

sudo zypper refresh
sudo zypper install noctalia

Unstable

sudo zypper refresh
sudo zypper install noctalia-git

Note

v5 will only be available for Tumbleweed and Slowroll. Leap 16.0 is unable to build because sdbus-c++ is still on v1.6.0 while v5 requires >= v2.x.x

• Stable version: Updated when a new release is tagged
• Unstable version: Automatically rebuilt on OBS whenever a new commit is pushed

---

Gentoo

Noctalia is available in the GURU overlay.

Gentoo exception

Gentoo packaging does not provide SLOTs for v4 and v5 as v4 will be dropped eventually, therefore they cannot be installed simultaneously.

Snapshots have been dropped in favor of official releases, so=gui-apps/noctalia-5.0.0_pre99999999 is now superseded by =gui-apps/noctalia-9999.

Step 1: Enable and sync the overlay as read in Project:GURU/Information_for_End_Users.

Step 2: Unmask the gui-apps/noctalia package:

gui-apps/noctalia **

Step 3: (Optional) Mask the live ebuild to use versioned releases

<=gui-apps/noctalia-9999

Step 4: Emerge the package:

emerge --ask gui-apps/noctalia

---

Void Linux

Noctalia is available through a custom XBPS repository.

Step 1: Add the repository source

echo "repository=https://repo.voiders.dev" | sudo tee /etc/xbps.d/10-voiders-community.conf

Step 2: Sync and install Noctalia

sudo xbps-install -S
sudo xbps-install noctalia

Note

If Noctalia fails to run, install the sdbus-c++ package.

Alternative: Build from source using xbps-src

# Install git, wget
sudo xbps-install git wget

# Set up the Void packages tree
git clone --depth 1 https://github.com/void-linux/void-packages.git
cd void-packages
./xbps-src binary-bootstrap

# Copy Noctalia build templates
mkdir srcpkgs/noctalia
wget https://git.voiders.dev/voiders-community/repository/raw/branch/main/pkgs/noctalia/template -P srcpkgs/noctalia/

# Build the packages
./xbps-src pkg noctalia

# Install the built packages
sudo xbps-install --repository=hostdir/binpkgs noctalia

---

GNU Guix

The Git repository of Noctalia is also available as a Guix channel. It provides a (noctalia) module with the noctalia-git package.

(channel
  (name 'noctalia)
  (url "https://github.com/noctalia-dev/noctalia")
  (branch "main"))

To use this channel, add it into your ~/.config/guix/channels.scm. For example:

(list (channel
        (name 'noctalia)
        (url "https://github.com/noctalia-dev/noctalia")
        (branch "main"))
      %default-guix-channel)

After updating channels via guix pull, Noctalia will be available to your Guix installation. Then you’re free to do what you want with the noctalia-git package ;-)

For example, spawn one-off software environment via guix shell:

guix shell noctalia-git

install it into your user profile via guix package:

guix install noctalia-git

declare it in your home environment (...s are placeholders for your existing configuration):

(use-modules (noctalia)
             ...)

(home-environment
  (packages
   (list noctalia-git
         ...))
  ...)

or whole-system configuration:

(use-modules (noctalia)
             ...)

(operating-system
  (packages
   (list noctalia-git
         ...))
  ...)

---

Debian

Noctalia provides an APT repository for Debian-based distributions.

Step 1: Install the repository signing key

wget https://pkg.noctalia.dev/deb/nickh-archive-keyring.deb && sudo dpkg -i nickh-archive-keyring.deb

Step 2: Add the repository

Debian Trixie

sudo wget -O /etc/apt/sources.list.d/noctalia-trixie.sources https://pkg.noctalia.dev/deb/noctalia-trixie.sources

Debian Sid

sudo wget -O /etc/apt/sources.list.d/noctalia-unstable.sources https://pkg.noctalia.dev/deb/noctalia-unstable.sources

Ubuntu 26.04

sudo wget -O /etc/apt/sources.list.d/noctalia-resolute.sources https://pkg.noctalia.dev/deb/noctalia-resolute.sources

Step 3: Install noctalia

sudo apt update
sudo apt install noctalia

Note

The APT repository provides amd64 packages only.

---

Manual Installation

Not Recommended

Manual installation has no easy upgrade path. You will need to manually download and replace files for each update. We strongly recommend using a package manager (Arch, Fedora) whenever possible.

If you prefer to install Noctalia locally or want more control over the installation process, you can install it manually to your user configuration directory. This method works on any Linux distribution.

Step 1: Sync and install dependencies

Arch

sudo pacman -S meson gcc just \
  wayland wayland-protocols \
  libglvnd freetype2 fontconfig \
  cairo pango \
  libxkbcommon glib2 \
  sdbus-cpp libpipewire wireplumber polkit \
  pam curl libwebp librsvg libqalculate

Fedora

sudo dnf install meson gcc-c++ just \
  wayland-devel wayland-protocols-devel \
  libEGL-devel mesa-libGLES-devel \
  freetype-devel fontconfig-devel \
  cairo-devel pango-devel \
  libxkbcommon-devel glib2-devel \
  sdbus-cpp-devel pipewire-devel wireplumber-devel \
  pam-devel polkit-devel libcurl-devel libwebp-devel librsvg2-devel \
  libqalculate-devel

Debian/Ubuntu

sudo apt install meson g++ just \
  libwayland-dev wayland-protocols \
  libegl-dev libgles-dev \
  libfreetype-dev libfontconfig-dev \
  libcairo2-dev libpango1.0-dev \
  libxkbcommon-dev libglib2.0-dev \
  libsdbus-c++-dev libpipewire-0.3-dev libwireplumber-0.5-dev \
  libpam0g-dev libpolkit-agent-1-dev libpolkit-gobject-1-dev \
  libcurl4-gnutls-dev libwebp-dev librsvg2-dev

Vendored dependencies, with no system package needed: Wuffs, nanosvg, nlohmann/json, Luau, dr_wav, fzy, stb_image_resize2, and Material Color Utilities.

Dependencies that are vendored by default, with a meson option to instead use the system package: tomlplusplus

System packages required beyond the Wayland/GL stack: libwebp handles WebP decoding and thumbnail encoding. Wuffs handles the other supported raster image formats.

Polkit agent support requires development files that provide the polkit-agent-1 and polkit-gobject-1 pkg-config modules. Some distros ship these in the runtime polkit package, while split-package distros use names such as polkit-devel, polkit-dev, or libpolkit-agent-1-dev / libpolkit-gobject-1-dev.

Optional: installing jemalloc (Fedora: jemalloc-devel, Arch: jemalloc, Debian/Ubuntu: libjemalloc-dev, Void: jemalloc) reduces memory fragmentation in long-running sessions. On glibc systems it is used automatically when detected. Use Meson’s -Djemalloc=enabled or -Djemalloc=disabled option to require or disable it explicitly.

Sanitizer runtime packages are only needed for ASan/UBSan builds configured with just configure asan.

Step 2: Prepare directory

git clone https://github.com/noctalia-dev/noctalia --branch main
cd noctalia

Step 3: Building and installing Noctalia

Requires just and meson.

Release Mode

# Optimized release build in build-release/
just configure release
just build release

# Install the selected build mode. This does not build or reconfigure.
sudo just install release

Pass a prefix to configure to install somewhere other than /usr/local:

just configure release "$HOME/.local"
just build release
just install release

To remove files installed from a build directory, run just uninstall release.

Debug Mode

# Debug build in build-debug/ for local development and troubleshooting.
just configure
just build

# Test your local debug build with
just run

Meson installs the binary and shipped assets using the normal prefix layout:

/usr/local/bin/noctalia
/usr/local/share/noctalia/assets/...

Noctalia needs the shipped assets/ tree at runtime. Copying only the noctalia binary is not enough.

Portable bundle layouts are also supported:

bundle/
  noctalia
  assets/

bundle/
  bin/noctalia
  share/noctalia/assets/

See CONTRIBUTING.md for the full runtime asset lookup order.

Getting Help

If you encounter issues during installation:

• Check our FAQ for common problems
• Visit our GitHub Issues page
• Join our community on Discord for real-time support