v5-getting-started-faq.md
Find answers to common setup and troubleshooting questions for Noctalia v5.
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.
No. Noctalia v5 is a fresh install, not an automatic upgrade from the Quickshell-based v4 line. It ships as a separate package, your package manager will not replace v4 with v5, and v4 settings are not migrated into v5.
On most distributions, you can keep v4 installed while you try v5. The packages do not conflict, so you can install both and run whichever version you want. Their configuration files do not conflict either: v4 config is JSON-only, v5 config is TOML, and their config file names are different. v5 may write separate state files, but its configuration is TOML.
The main thing you need to adjust is your compositor keybinds. Keybinds live in your compositor config, not in Noctalia’s package, so update the bindings that launch the Noctalia launcher, panels, settings UI, or other commands when switching between v4 and v5.
See the Installation guide and Running Noctalia for setup steps.
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.
Noctalia does not manage session autostart from its Settings app. Use your compositor’s autostart mechanism instead.
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.
Section titled “Configuration”
If you only use Settings, you normally do not need to edit config files. Settings writes your changes to ~/.local/state/noctalia/settings.toml.
If you write config by hand, put it in ~/.config/noctalia/. Noctalia reads every *.toml file in that directory, sorted alphabetically, and merges them.
Settings changes load after hand-written config, so they win when both layers define the same setting. If a value in your file looks ignored, check Settings first, or inspect ~/.local/state/noctalia/settings.toml.
See How configuration works for the full load order and export options.
Widget settings are attached to the widget name used in the bar list. If you place the same name twice, both entries use the same configuration.
In Settings, open the Add widget selector and turn on the Named Widget toggle at the top before choosing the widget type. Create one named widget for each copy you want to configure separately. Middle-click a widget to open the Settings page for that exact instance.
In text config, give each copy its own name, then set type to the widget you want:
[bar.main]end = ["sysmon-left", "sysmon-right"]
[widget.sysmon-left]type = "sysmon"# settings for the first sysmon
[widget.sysmon-right]type = "sysmon"# settings for the second sysmon
See Widget definitions for more examples.
This is not a Noctalia setting. There is no Settings toggle or TOML key for it in v5.
Noctalia follows your system locale, so set the first day of the week through your system’s LC_TIME locale.
This is different from v4, which had a Noctalia-specific override. In v5, calendar and localized date behavior come from the active system locale.
Start with compositor output scaling. That is the correct way to handle HiDPI monitors and affects all Wayland clients consistently.
For Noctalia-specific sizing in Settings:
In text config, the main keys are shell.ui_scale, [bar.<name>].scale, and [widget.<name>].scale.
See Shell settings and Bars.
On Niri, making a bar transparent only changes Noctalia surface opacity. When Niri ext-background-effects support is active, Noctalia still publishes blur regions for its layer surfaces, so the compositor can keep blurring behind the bar.
To disable that blur, keep the Noctalia layer-rule in your Niri config and set blur false inside its background-effect block. See Niri compositor settings: Blur for the full rule and notes.
Attached panels (like the control center) sit flush against the bar, so the line where they meet, the seam, can show a faint cut, a hairline gap, or a doubled edge depending on your compositor and display scaling. These artifacts mostly show up with a highly transparent bar, where the seam between the two surfaces has nothing opaque to hide behind. If the seam bothers you, the simplest fix is to raise background_opacity toward 1.0; the settings below help when you want to keep the transparency. Three settings control how that seam looks.
Hide or tune the cut with panel_overlap. This sets how many logical pixels an attached panel is pulled into the bar so the two surfaces share one edge. The default is 1. If you see a faint seam line, try 0; if a gap appears, raise it; negative values push the panel away from the bar. The right value depends on the output’s fractional scale, so on a mixed-scale multi-monitor setup you can set it per monitor with a [bar.<name>.monitor.*] override. In Settings it lives under Bar → Layout → Advanced.
Embrace the cut with contact_shadow. Instead of hiding the seam, this draws a dark gradient where the panel meets the bar, giving the panel a lifted-off-the-bar feel. It is independent of the bar’s shadow and only affects attached panels; the change applies the next time a panel opens. In Settings it lives under Bar → Effects.
Mind the compositor blur. The bar and an attached panel are separate Wayland surfaces, so the compositor blurs each one on its own. With a large blur sampling offset the two blur passes don’t line up at the seam, and the gap between them becomes visible. How much shows up depends on the compositor: Hyprland handles it well, while Niri tends to reveal the split more. If the seam looks off with blur, lower your compositor’s blur size/passes (or its sampling offset) rather than chasing it with panel_overlap.
[bar.main]panel_overlap = 0 # 1 is default; 0 removes the overlap, negative pushes the panel awaycontact_shadow = true # dark gradient at the seam for a lifted look
See Bars for the full per-bar and per-monitor field list.
Noctalia follows your system locale by default.
In Settings, use Appearance → Interface → Language.
In text config, set shell.lang:
[shell]lang = "fr"
If a translation is not available for that language, untranslated strings fall back to English. Language values may use BCP-47 tags such as pt-BR and zh-Hans, or POSIX locale names such as pt_BR.UTF-8. For Chinese locales without an explicit script, Noctalia derives the script from the region: for example zh_CN matches zh-Hans.
If you manage wallpapers with another tool such as waypaper, swww, or hyprpaper, let that app draw the wallpaper and let Noctalia use the image only for color extraction.
In Settings:
In text config:
# Disable Noctalia wallpaper display[wallpaper]enabled = false
# Generate colors from the current wallpaper path[theme]source = "wallpaper"wallpaper_scheme = "m3-content"
After your wallpaper app sets a new image, tell Noctalia which file to use for color extraction:
Terminal window
noctalia msg wallpaper-set ~/Pictures/Wallpapers/new-wallpaper.png
Noctalia extracts colors from that image, generates a palette with the configured scheme, and cross-fades the shell to the new colors even though it is not displaying the wallpaper itself. The path is persisted across restarts.
Section titled “Troubleshooting”
Check these points first:
noctalia msg ....Noctalia Settings does not create compositor keybinds. Keybinds belong in your compositor’s configuration; Noctalia only receives the IPC command.
See the IPC overview and Shell commands.
#Why are my tray icons missing after (re)starting Noctalia?
This typically happens when KDE is installed alongside your window manager. KDE’s tray daemon (kded6) can interfere with Noctalia’s system tray, though it usually doesn’t autostart at cold boot.
Common cause: Opening Dolphin (KDE’s file manager) with sudo or elevated privileges will respawn kded6, which can cause tray icons to disappear.
Solution: Manually stop the process
Run this command, then restart Noctalia:
Terminal window
pkill kded6
You can also add this to your compositor’s autostart configuration if needed:
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, middle-click the battery widget and choose its Device setting. In text config, set the widget’s device key.
See the battery widget docs.
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.
Weather and Night Light both use Settings → Location. Set Auto locate or enter an Address there first.
For Weather, also enable Location → Weather. The bar weather widget requires the weather service to be enabled.
For Night Light, also enable Location → Night Light. Night Light requires compositor support for the wlr-gamma-control protocol.
In text config, Weather requires [weather] enabled = true plus a resolved [location] source such as auto_locate = true or address = "...".
Weather, Theme auto, and Night Light all share the same location source.
See Location, Theme, and Night Light.
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.
If your wireless management tools (like NetworkManager or desktop applets) fail to communicate with wpa_supplicant, it is often a matter of missing D-Bus permissions or incorrect service options. The steps below allow users in the wheel group to interact with the wpa_supplicant daemon.
1. Update the D-Bus configuration
Explicitly allow the wheel group to send and receive signals via the fi.w1.wpa_supplicant1 interface. Open /etc/dbus-1/system.d/wpa_supplicant.conf and ensure the <policy group="wheel"> block is included before the closing </busconfig> tag:
/etc/dbus-1/system.d/wpa_supplicant.conf
<!DOCTYPE busconfig PUBLIC "-//freedesktop//DTD D-BUS Bus Configuration 1.0//EN" "http://www.freedesktop.org/standards/dbus/1.0/busconfig.dtd"><busconfig> <policy user="root"> <allow own="fi.w1.wpa_supplicant1"/>
<allow send_destination="fi.w1.wpa_supplicant1"/> <allow send_interface="fi.w1.wpa_supplicant1"/> <allow receive_sender="fi.w1.wpa_supplicant1" receive_type="signal"/> </policy> <policy context="default"> <deny own="fi.w1.wpa_supplicant1"/> <deny send_destination="fi.w1.wpa_supplicant1"/> <deny receive_sender="fi.w1.wpa_supplicant1" receive_type="signal"/> </policy>
<!-- Allow users in the wheel group to interact with wpa_supplicant --> <policy group="wheel"> <allow send_destination="fi.w1.wpa_supplicant1"/> <allow receive_sender="fi.w1.wpa_supplicant1" receive_type="signal"/> </policy></busconfig>
2. Configure the runit service flags
For D-Bus control to function correctly, wpa_supplicant must be started with the -u flag. Update (or create) the service configuration file:
/etc/sv/wpa_supplicant/conf
OPTS="-u -M -c /etc/wpa_supplicant/wpa_supplicant.conf"
3. Apply the changes
After saving both files, restart the D-Bus daemon and the wpa_supplicant service:
Terminal window
# Reload D-Bus configurationsudo pkill -HUP dbus-daemon
# Restart the wpa_supplicant runit service if you hit the service-flags issuesudo sv restart wpa_supplicant