Running the shell

Autostart by your Wayland compositor

This is the recommended method for launching noctalia-shell, as it integrates with your window manager.

For the Niri compositor, add the following line to the end of your configuration file, typically located at ~/.config/niri/config.kdl

spawn-at-startup "qs" "-c" "noctalia-shell"

For the Hyprland compositor, append this line to your configuration file, typically located at ~/.config/hypr/hyprland.conf

exec-once = qs -c noctalia-shell

Running as a Systemd Service (Advanced)

For more robust process management, you can configure Noctalia to run as a systemd user service. This approach provides automatic restarts on failure and centralizes logging with journalctl.

1. Create the service file

First, create a new service definition file at ~/.config/systemd/user/noctalia.service with the following content:

[Unit]
Description=Noctalia Shell Service
PartOf=graphical-session.target
Requisite=graphical-session.target
After=graphical-session.target

[Service]
ExecStart=qs -c noctalia-shell
Restart=on-failure
RestartSec=1

[Install]
WantedBy=graphical-session.target

2. Enable and Start the Service

Next, enable the service to have it start automatically with your graphical session.

Niri

If you use a compositor like Niri, it’s best to tie Noctalia directly to it. This ensures they start and stop together and passes critical environment variables to the service.

# Example for Niri users
systemctl --user add-wants niri.service noctalia.service

# Start the service
systemctl --user start noctalia.service

Other Compositors (no UWSM)

If you use a compositor which doesn’t provide services or targets to bind to (in this example Hyprland), then:

To launch the provided AUR service file Noctalia ships (and any others which bind to graphical-session.target) without having to resort to using UWSM:

1. Create a target file

At ~/.config/systemd/user/, I called mine hyprland-session.target, with contents of:

[Unit]
Description=Hyprland Session Target
Requires=graphical-session.target
After=graphical-session.target

(Description contents can be whatever you like.)

2. Adjust your compositor configuration file

In the section that starts things, after any and all environment variables (where everything should be anyway), add the following before anything else (Hyprland syntax in this case again, adjust as needed):

exec-once = dbus-update-activation-environment --systemd --all
exec-once = systemctl --user start hyprland-session.target

3. Bind service to compositor target

Do not enable it, this will cause it to run on any DE/WM! (If you already did so, just disable it.) This example is for Hyprland:

systemctl --user add-wants hyprland-session.target noctalia.service

Optionally bind xdg-desktop-autostart to it as well:

systemctl --user add-wants hyprland-session.target xdg-desktop-autostart.target

4. Lastly

Reboot, re-log in, or simply run systemctl --user start hyprland-session.target (or however you named it for your compositor) and everything set to start with your compositor of choice (Hyprland in this case), including Noctalia, will start and stop when you log out or stop the target for whatever reason.

Finally, go into Settings -> Launcher -> Execute and tick on Enable custom launch prefix with a value of:

systemd-run --user --scope --collect

You may want to additionally add everything that executes into a different slice, or a sub-slice or an existing slice or a sub-slice of an existing slice, by appending for example --slice=desktop.slice at the end to make up a new user slice called “desktop” or --slice=app-desktop.slice to add it to an existing user slice (app) under a made up slice “desktop”.

Manual Launch for Debugging

The most direct way to run Noctalia for testing or debugging is to invoke it through Quickshell. Open a terminal and execute:

qs -c noctalia-shell