v5-greeter.md
Noctalia Greeter is the screen you see before your desktop session starts. It lets you pick a user, enter your password, choose a Wayland session, and pick a color scheme - with the same visual language as Noctalia.
It is built for greetd: greetd starts the bundled wlroots compositor (noctalia-greeter-compositor), and the greeter runs inside that session. It is a login UI only, not a desktop shell or compositor replacement.
Pair it with Noctalia v5 if you want your wallpaper and palette copied from the shell to the login screen (optional).
Install noctalia-greeter from your distribution if a package is available. You also need greetd , D-Bus , and polkit on the machine where greetd runs.
For user avatars in the login picker, also install and enable accountsservice (usually the accounts-daemon service). Noctalia Greeter reads each user’s avatar from org.freedesktop.Accounts and shows a fallback when that service is unavailable or has no IconFile set.
Your desktop sessions (niri, Hyprland, and so on) are separate - install those as you normally would.
If your distro does not package the greeter yet, see the noctalia-greeter repository for build and install steps. After installing, run the included system setup script as root so /var/lib/noctalia-greeter/ and greeter.toml are created for the greetd user.
Section titled “Setting up greetd”
Point greetd at the installed session wrapper. Use the path on your system - do not assume /usr/local if you installed from a package:
Terminal window
which noctalia-greeter-session
Example for a manual install to /usr/local (replace the path if which shows something else, e.g. /usr/bin/noctalia-greeter-session):
[default_session]command = "/usr/local/bin/noctalia-greeter-session"user = "greeter"
Use the user value that matches your greetd config. The greeter setup script prints a ready-to-paste config.toml block with the path it finds.
Section titled “Default session”
To open the greeter with a specific session already selected, pass --session on the command line. The name must match a session from the greeter picker exactly (for example niri):
command = "/usr/bin/noctalia-greeter-session -- --session niri"
List valid session names:
Terminal window
noctalia-greeter sessions
You can also set [session].default in greeter.toml - that overrides the last session you picked unless --session is passed on the command line.
To skip the user list and open the password step for a specific account (similar to tuigreet’s default user), set [user].default in greeter.toml or pass --user on the command line:
command = "/usr/bin/noctalia-greeter-session -- --user lysec"
Use the exact login name from /etc/passwd. Esc or the back button returns to the user list if you need another account.
Restart greetd after changing its config:
Terminal window
sudo systemctl restart greetd
On runit:
Terminal window
sudo sv restart greetd
Section titled “Matching your Noctalia desktop”
With Noctalia v5 and the greeter both installed, open Settings → Security → Noctalia Greeter → Sync Now. Noctalia copies your wallpaper, palette, enabled session actions (shell.session plus [shell.session.power] overrides), and (when you use multiple monitors) monitor layout to the greeter (you will be prompted for admin access via polkit, through pkexec or run0).
User avatars are not part of greeter appearance sync. They come from AccountsService, so keep accountsservice running if you want the avatar you picked in Noctalia to appear on the greeter too.
Enable Settings → Security → Auto-Sync Greeter to automatically sync whenever your wallpaper, colors, or theme mode change. Syncing triggers after a short debounce so rapid changes (like dragging a color picker) are batched into one sync.
Sync Now shows a notification while it waits for that approval. If logind or elogind is running, enable Settings → Security → Polkit agent to approve from the desktop.
seatd without logind: polkit has no graphical session to attach to, so Noctalia’s polkit agent cannot register (No session for pid in the log). Sync Now stages files and shows the install command. Run it from a terminal:
Terminal window
pkexec noctalia-greeter-apply-appearance "$XDG_RUNTIME_DIR/noctalia-greeter-sync"
To run Sync Now from the desktop on seatd, set a custom privilege prefix (the apply helper path and staging directory are appended automatically):
[shell.greeter_sync]privilege_command = "ghostty -e pkexec"
Optional: install elogind if you want in-session polkit prompts without a terminal wrapper. seatd and elogind can coexist; elogind only provides session tracking for polkit, not power management.
Synced data is installed to /var/lib/noctalia-greeter/appearance.json (root-owned, world-readable). greeter.toml in the same directory is separate greetd preferences.
After syncing, log out or restart greetd to see the changes on the login screen.
The greeter adds a Synced color scheme when sync data is present. Session and scheme choices you make on the login screen are remembered in /var/lib/noctalia-greeter/greeter.toml.
For monitor selection, UI scale, cursor theme, and other admin settings, see Configuration.
The greeter works without a mouse.
| Key | Action |
|---|---|
Tab / Shift+Tab | Move focus |
↑ / ↓ | Move focus, or move in an open menu |
Enter | Submit password / activate / confirm menu |
Space | Activate focused control |
Esc | Close menu or leave password step |
F3 | Session picker |
F7 | Color scheme picker |
Ctrl+Alt+F1–F12 | Switch to virtual terminal (TTY) |
Section titled “Troubleshooting”
/var/log/noctalia-greeter.log and /var/lib/noctalia-greeter/greeter.log. If the log files are missing, run just setup-log-dir from the greeter source tree (or create them manually with the greetd user as owner).Failed to spawn client / wrong path in greetd config - command must be the full path from which noctalia-greeter-session (often /usr/bin/... on packaged installs, not /usr/local/bin/...).WAYLAND_DISPLAY is not set - greetd must use noctalia-greeter-session (it starts noctalia-greeter-compositor). Fix command in /etc/greetd/config.toml./var/log/noctalia-greeter.log and /var/lib/noctalia-greeter/greeter.log when those paths are writable. Create them once during setup if needed.[session].default is set in greeter.toml, it wins over last-used [session].last. Run noctalia-greeter sessions for exact Name spelling.accounts-daemon. The greeter reads the avatar from the user’s AccountsService IconFile; without it, the picker falls back to a placeholder.pkexec or run0 on PATH (for example when pkexec is disabled on NixOS, install run0 from systemd ≥ 256). A polkit authentication agent must be running in your session.appearance.json - Sync stages files first, then waits for polkit to authorize noctalia-greeter-apply-appearance. On seatd without logind , Noctalia’s polkit agent cannot register; run the pkexec command from the Sync Now notification in a terminal. Sync Now warns after 90 seconds if approval is still pending.No session for pid - Expected on seatd-only setups. Install elogind for in-session prompts, or use terminal/console pkexec for greeter sync.[output].scale in greeter.toml. See Configuration.[cursor].theme (and [cursor].size) in greeter.toml, or the XCURSOR_* variables in the greetd command. If the theme is not on the default search path, also set [cursor].path / XCURSOR_PATH. See Cursor theme.