Skip to content
Noctalia Noctalia
FAQ

Installation

Noctalia v5 is available on the following distributions:

You can also install manually on any other Linux distribution.

Arch Linux

Section titled “Arch Linux”
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

Fedora

Section titled “Fedora”

Noctalia is available via 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

Installing noctalia-git will automatically install all runtime dependencies and display optional dependencies.

openSUSE

Section titled “openSUSE”

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

Step 2: Refresh and install noctalia:

Terminal window
sudo zypper refresh
sudo zypper install noctalia

Gentoo

Section titled “Gentoo”

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: Mask Noctalia v4:

~gui-apps/noctalia-9999

Step 4: (Optional) Mask the live ebuild for Noctalia v5 to use a snapshot instead:

~gui-apps/noctalia-5.0.0_pre99999999

Step 5: Emerge the package:

Terminal window
emerge --ask gui-apps/noctalia

Void Linux

Section titled “Void Linux”

Noctalia is available through a custom XBPS repository.

Step 1: Add the repository source

Terminal window
echo "repository=https://universalrepository.pages.dev/void" \
| sudo tee /etc/xbps.d/10-noctalia.conf

Step 2: Sync and install noctalia

Terminal window
sudo xbps-install -S
sudo xbps-install noctalia

GNU Guix

Section titled “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:

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
         ...))
  ...)

Debian

Section titled “Debian”

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

Step 3: Install noctalia

Terminal window
sudo apt update
sudo apt install noctalia

Manual Installation

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 polkit \
  pam curl libwebp librsvg libqalculate

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

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 main
cd noctalia

Step 3: Building and installing Noctalia

Requires just and meson.

Terminal window
# 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:

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

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

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

Section titled “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