Skip to content
Noctalia Noctalia
FAQ

Installation

Noctalia is packaged for Arch Linux, NixOS, and Gentoo, but can also be installed manually in other distributions.

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-shell

Development Version

Section titled “Development Version”

For the latest features and fixes, you can install the development version directly from the Git repository:

Terminal window
paru -S noctalia-shell-git

Gentoo

Section titled “Gentoo”

Noctalia-shell is available in the Gentoo Guru repository.

First enable and sync the repository as described at Guru Information for End Users:

Terminal window
# eselect repository enable guru
# emerge --sync guru

Next, update the /etc/portage/package.accept_keywords file/folder to enable the unstable keyword on the noctalia-shell package:

gui-apps/noctalia-shell ~amd64

Now the package can be installed through emerge:

Terminal window
# emerge gui-apps/noctalia-shell

Read the post-install emerge messages for information on optional dependencies and emerge them as well if desired.

For integration with systemd the package installs a user service unit to /usr/lib/systemd/user/noctalia.service.

Fedora

Section titled “Fedora”

Noctalia-shell is available in the Terra repository.

First install the repository as described on the website:

Terminal window
sudo dnf install --nogpgcheck --repofrompath 'terra,https://repos.fyralabs.com/terra$releasever' terra-release

Next, install the noctalia-shell package:

Terminal window
sudo dnf install noctalia-shell

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

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: Install required dependencies

For Arch Linux:

Terminal window
# Core dependencies (required)
paru -S quickshell brightnessctl git imagemagick python


# Desktop monitor brightness (may cause instability with some monitors)
paru -S ddcutil


# Optional dependencies
paru -S cliphist cava wlsunset xdg-desktop-portal python3 evolution-data-server

For other distributions, install the equivalent packages using your package manager.

Step 2: Download and install Noctalia

Terminal window
mkdir -p ~/.config/quickshell/noctalia-shell && curl -sL https://github.com/noctalia-dev/noctalia-shell/releases/latest/download/noctalia-latest.tar.gz | tar -xz --strip-components=1 -C ~/.config/quickshell/noctalia-shell

Dependencies Explained

Section titled “Dependencies Explained”

Required:

  • quickshell - Core shell framework
  • brightnessctl - Internal/laptop monitor brightness control
  • imagemagick - Required for template processing & wallpaper resizing
  • python - Required for template processing
  • git - Required for update checking and the plugin system

Hardware-specific:

  • ddcutil - Desktop monitor brightness control (⚠️ may introduce system instability with certain monitors)

Optional but recommended:

  • cliphist - Clipboard history support
  • cava - Audio visualizer component
  • wlsunset - Night light functionality
  • xdg-desktop-portal - Enables “Portal” option in screen recorder
  • python3, evolution-data-server - Calendar events

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