Installation

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).

Installing
Setting up greetd
Matching your Noctalia desktop
Keyboard
Troubleshooting

Installing

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.

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.conf are created for the greetd user.

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:

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.

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:

noctalia-greeter sessions

You can also set default_session in greeter.conf - that overrides the last session you picked unless --session is passed on the command line.

Default user

To skip the user list and open the password step for a specific account (similar to tuigreet’s default user), set default_user in greeter.conf 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:

sudo systemctl restart greetd

On runit:

sudo sv restart greetd

Matching your Noctalia desktop

With Noctalia v5 and the greeter both installed, open Settings → Security → Noctalia Greeter → Sync Now. Noctalia copies your wallpaper, palette, and (when you use multiple monitors) monitor layout to the greeter (you will be prompted for admin access via polkit, through pkexec or run0).

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.conf.

For monitor selection, UI scale, cursor theme, and other admin settings, see Configuration.

Keyboard

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)

Troubleshooting

Blank screen - Check /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.
Black screen after reboot - Session logs are written to /var/log/noctalia-greeter.log and /var/lib/noctalia-greeter/greeter.log when those paths are writable. Create them once during setup if needed.
Wrong session on startup - If default_session is set in greeter.conf, it wins over last-used session. Run noctalia-greeter sessions for exact Name spelling.
Synced look missing - Install Noctalia v5, the greeter, and the polkit policy; sync again from Settings; restart greetd or log out once.
Sync fails with no privilege escalator - Greeter sync needs 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.
UI too small or too large on a high-DPI monitor - Set scale in greeter.conf. See Configuration.
Wrong or default cursor theme - Set cursor_theme (and cursor_size) in greeter.conf, 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.