v5-getting-started-installation.md
Noctalia v5 is available on the following distributions:
You can also install manually on any other Linux distribution.
Section titled “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.
Please replace with your AUR helper of choice.
Terminal window
paru -S noctalia-git
Terminal window
git clone https://aur.archlinux.org/noctalia-gitcd noctalia-gitmakepkg -is
Noctalia is available from the default repos for Fedora 44 and up.
Step 1 : Install noctalia
Terminal window
sudo dnf install noctalia
An alternate version using git snapshots is available from the LionHeartP Copr repository.
Step 1 : Enable the repository
Terminal window
sudo dnf copr enable lionheartp/Hyprland
Step 2 : Install noctalia
Terminal window
sudo dnf install noctalia-git
Noctalia is available via home:neifua:Noctalia repository on the openSUSE Build Service.
Step 1 : Add the OBS repository
Terminal window
sudo zypper addrepo --refresh --name noctalia-v5 https://download.opensuse.org/repositories/home:neifua:Noctalia/openSUSE_Tumbleweed/home:neifua:Noctalia.repo
Terminal window
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:
Terminal window
sudo zypper refreshsudo zypper install noctalia
Terminal window
sudo zypper refreshsudo zypper install noctalia-git
Noctalia is available in the GURU overlay.
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:
Terminal window
emerge --ask gui-apps/noctalia
Noctalia is available through a custom XBPS repository.
Step 1 : Add the repository source
Terminal window
echo "repository=https://repo.voiders.dev" | sudo tee /etc/xbps.d/10-voiders-community.conf
Step 2 : Sync and install Noctalia
Terminal window
sudo xbps-install -Ssudo xbps-install noctalia
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:
Terminal window
guix shell noctalia-git
install it into your user profile via guix package:
Terminal window
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 ...)) ...)
Noctalia provides an APT repository for Debian-based distributions.
Step 1 : Import the repository signing key
Terminal window
curl -fsSL https://pkg.noctalia.dev/gpg.key | sudo gpg --dearmor -o /etc/apt/keyrings/noctalia.gpg
Step 2 : Add the repository
Terminal window
echo "deb [signed-by=/etc/apt/keyrings/noctalia.gpg] https://pkg.noctalia.dev/apt trixie main" | sudo tee /etc/apt/sources.list.d/noctalia.list
Terminal window
echo "deb [signed-by=/etc/apt/keyrings/noctalia.gpg] https://pkg.noctalia.dev/apt sid main" | sudo tee /etc/apt/sources.list.d/noctalia.list
Terminal window
echo "deb [signed-by=/etc/apt/keyrings/noctalia.gpg] https://pkg.noctalia.dev/apt plucky main" | sudo tee /etc/apt/sources.list.d/noctalia.list
Terminal window
echo "deb [signed-by=/etc/apt/keyrings/noctalia.gpg] https://pkg.noctalia.dev/apt questing main" | sudo tee /etc/apt/sources.list.d/noctalia.list
Step 3 : Install noctalia
Terminal window
sudo apt updatesudo apt install noctalia
Section titled “Manual Installation”
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
Terminal window
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
Terminal window
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
Terminal window
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
Terminal window
git clone https://github.com/noctalia-dev/noctalia --branch maincd noctalia
Step 3 : Building and installing Noctalia
Terminal window
# Optimized release build in build-release/just configure releasejust 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:
Terminal window
just configure release "$HOME/.local"just build releasejust install release
To remove files installed from a build directory, run just uninstall release.
Terminal window
# Debug build in build-debug/ for local development and troubleshooting.just configurejust build
# Test your local debug build withjust 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.
If you encounter issues during installation: