FAQ

Find answers to common setup and troubleshooting questions for Noctalia v5.

Setup

What distributions are supported?

Noctalia v5 is packaged for Arch Linux, NixOS, Fedora, openSUSE, and Void Linux. You can also install it manually on other Linux distributions if the required build and runtime dependencies are available.

See the Installation guide for distro-specific commands and manual install steps.

Should I use v4 or noctalia-qs instructions with v5?

No. Noctalia v5 is a native C++ and OpenGL ES shell launched with noctalia. The v4 line is Quickshell-based and uses qs / noctalia-qs, so v4 commands and configuration examples should not be copied into a v5 setup.

If you are using the Quickshell-based version, use the v4 documentation instead.

How do I start Noctalia automatically?

Use your compositor’s autostart mechanism. Examples for each supported compositor:

If your compositor expects startup commands to return after the shell has initialized, use noctalia --daemon. See the Running Noctalia page for details.

Configuration

Where should I put my config, and why is my setting ignored?

Put hand-written config in ~/.config/noctalia/. Noctalia reads every *.toml file in that directory, sorted alphabetically, and merges them.

Settings changed through the UI are written to ~/.local/state/noctalia/settings.toml. That file loads after your config files, so it wins when both layers define the same setting.

See How configuration works for the full load order and export options.

How can I make the UI bigger or smaller?

Start with compositor output scaling. That is the correct way to handle HiDPI monitors and affects all Wayland clients consistently.

For Noctalia-specific sizing:

Use shell.ui_scale for non-bar shell UI such as panels, launcher, clipboard, and settings.
Use bar.scale for bar widget content.
Use widget-specific size settings where available.

See Shell settings and Bars.

How can I get Noctalia to display in my language?

Noctalia follows your system locale by default. You can override language detection with shell.lang:

[shell]
lang = "fr"

If a translation is not available for that language, untranslated strings fall back to English.

Troubleshooting

Why aren't my keybinds working?

Check these points first:

Make sure Noctalia is running.
Use v5 IPC commands in the form noctalia msg ....
Verify that your compositor bind syntax is correct.
Test the command in a terminal before putting it in a compositor config.

See the IPC overview and Shell & UI commands.

Why is my battery widget missing?

Battery status comes from UPower. Make sure UPower is installed and running.

On NixOS, enable:

services.upower.enable = true;

The battery widget defaults to the system battery. If you want to show a peripheral or second battery, configure the widget’s device setting. See the battery widget docs.

Why won't an app appear in the launcher or dock?

Noctalia discovers desktop applications from .desktop files in standard application directories. If an app is missing, verify that it installs a desktop entry under a path such as:

/usr/share/applications/
~/.local/share/applications/
$HOME/.nix-profile/share/applications/
/etc/profiles/per-user/$USER/share/applications/

For dock pins, match the desktop entry ID, StartupWMClass, display name, or full desktop entry path. See the Dock page for matching rules.

Why are weather or Night Light not working?

Weather requires [weather] enabled = true plus either auto_locate = true or an address. The weather widget also requires the weather service to be enabled.

Night Light can use the weather location for sunrise and sunset, or fall back to explicit schedule/location settings. It also needs compositor support for the wlr-gamma-control protocol.

See Services and Night Light.

Why can't I unlock my lock screen?

Noctalia v5 authenticates through PAM using the login service. Make sure /etc/pam.d/login exists and is valid for your distribution.

If you changed your PAM stack for fingerprint, security key, or other authentication methods, make sure those changes are present in the login PAM service used by Noctalia.