Skip to content
Noctalia Noctalia
FAQ

Installation

Noctalia 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 in the LionHeartP Copr repository.

First install the repository as described on the website:

Terminal window
sudo dnf copr enable lionheartp/Hyprland

Next, install the noctalia-shell package:

Terminal window
sudo dnf install noctalia-shell-v5

Installing noctalia-shell from Terra will automatically install all runtime dependencies and display optional dependencies.

openSUSE

Section titled “openSUSE”

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

First add the repository

Terminal window
sudo zypper addrepo --refresh https://download.opensuse.org/repositories/home:neifua/openSUSE_Tumbleweed/home:neifua.repo

Next, refresh and install the v5 package:

Terminal window
sudo zypper refresh
sudo zypper install 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

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

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.

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

Step 2: Prepear directory

Terminal window
git clone https://github.com/noctalia-dev/noctalia-shell --branch v5
cd noctalia-shell

Step 3: Build noctalia

Requires just and meson.

Terminal window
# Debug build in build-debug/
just configure
just build
just run


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


# Clean rebuild
just rebuild
just rebuild release

Step 4: Installation

After building, install with just:

Terminal window
sudo just install 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