https://github.com/noctalia-dev/noctalia-greeter

Last synced: about 1 month ago
JSON representation

Host: GitHub
URL: https://github.com/noctalia-dev/noctalia-greeter
Owner: noctalia-dev
License: mit
Created: 2026-05-15T11:03:10.000Z (3 months ago)
Default Branch: main
Last Pushed: 2026-06-08T11:19:59.000Z (about 2 months ago)
Last Synced: 2026-06-08T12:25:51.525Z (about 2 months ago)
Language: C++
Size: 2.3 MB
Stars: 1
Watchers: 0
Forks: 0
Open Issues: 0
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE

Awesome Lists containing this project

README

Noctalia Greeter
===

A minimal login greeter for [greetd](https://github.com/kennylevinsen/greetd) that matches the look and feel of [Noctalia Shell](https://github.com/noctalia-dev/noctalia-shell).

## What is Noctalia Greeter?

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

It is built for **greetd**: greetd starts the bundled wlroots compositor (`noctalia-greeter-compositor`), and the greeter runs inside that session.

Pair it with **[Noctalia v5](https://github.com/noctalia-dev/noctalia)** if you want wallpaper and palette synced from the shell settings (optional).

## Dependencies

Install everything below on the machine where greetd will run. Each list covers build tools and libraries, plus **greetd** and **D-Bus** (used by `noctalia-greeter-session`). You still need your desktop sessions separately (niri, Hyprland, and so on).

### Arch

```sh
sudo pacman -S meson gcc just \
greetd dbus \
wayland wayland-protocols wlroots0.20 \
libglvnd freetype2 fontconfig \
cairo pango harfbuzz \
libxkbcommon glib2 \
libwebp librsvg
```

### Fedora

```sh
sudo dnf install meson gcc-c++ just \
greetd dbus \
wayland-devel wayland-protocols-devel wlroots-devel \
libEGL-devel mesa-libGLES-devel \
freetype-devel fontconfig-devel \
cairo-devel pango-devel harfbuzz-devel \
libxkbcommon-devel glib2-devel \
libwebp-devel librsvg2-devel
```

### Debian / Ubuntu

```sh
sudo apt install meson g++ just \
greetd dbus \
libwayland-dev wayland-protocols libwlroots-0.20-dev \
libegl-dev libgles-dev \
libfreetype-dev libfontconfig-dev \
libcairo2-dev libpango1.0-dev libharfbuzz-dev \
libxkbcommon-dev libglib2.0-dev \
libwebp-dev librsvg2-dev
```

### Void Linux

```sh
sudo xbps-install meson ninja pkg-config git \
greetd dbus \
wayland-devel wayland-protocols wlroots-devel libepoxy-devel \
MesaLib-devel libglvnd-devel cairo-devel \
pango-devel fontconfig-devel freetype-devel harfbuzz-devel \
libxkbcommon-devel libwebp-devel librsvg-devel
```

Vendored dependencies, with no system package needed: `nlohmann/json`, `stb`, and `Wuffs`.

Build requires `wlroots-0.20` and `wayland-server` development packages (see distro lists above).

`libwebp` handles WebP wallpapers when syncing appearance from the shell. Wuffs handles other raster image formats.

On Void Linux, `libepoxy-devel` is used when EGL/GLES pkg-config modules are not available.

## NixOS

A flake and NixOS module are provided.

Add the input to your `flake.nix`:

```nix
inputs = {
noctalia-greeter = {
url = "github:noctalia-dev/noctalia-greeter";
inputs.nixpkgs.follows = "nixpkgs";
};
};
```

Import the module and enable the greeter in your configuration:

```nix
imports = [
inputs.noctalia-greeter.nixosModules.default
];

programs.noctalia-greeter = {
enable = true;
package = inputs.noctalia-greeter.packages.${pkgs.stdenv.hostPlatform.system}.default;

# Optional configuration
greeter-args = "";
settings.cursor = {
theme = "Adwaita";
size = 24;
package = pkgs.adwaita-icon-theme;
};
};
```

The module enables greetd and sets the session command automatically.

`greeter-args` passes extra flags to `noctalia-greeter-session`, for example
`--session ` to set a default session. Run `noctalia-greeter sessions`
to list valid names.

## Building and installing

Requires [just](https://github.com/casey/just) and [meson](https://mesonbuild.com/).

#### Release build

```sh
just configure-release
just build-release
sudo meson install -C build-release
sudo ./scripts/setup_greeter_system.sh
```

Pass a prefix when configuring to install somewhere other than `/usr/local`:

```sh
meson setup build-release --prefix="$HOME/.local" --buildtype=release --reconfigure
just build-release
sudo meson install -C build-release
sudo ./scripts/setup_greeter_system.sh
```

#### Debug build

```sh
just build
sudo just install
```

`just install` runs the same system setup scripts after Meson install.

Meson installs the greeter binary, session launcher and assets. With the default prefix that is under `/usr/local`; distro packages (e.g. AUR) usually install to `/usr/bin` instead.

```text
/bin/noctalia-greeter
/bin/noctalia-greeter-compositor
/bin/noctalia-greeter-session
/bin/noctalia-greeter-apply-appearance
/share/noctalia-greeter/assets/...
```

The greeter needs the shipped `assets/` tree at runtime. Copying only the `noctalia-greeter` binary is not enough.

## 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:

```sh
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`):

```toml
[default_session]
command = "/usr/local/bin/noctalia-greeter-session"
user = "greeter"
```

Use the `user` value that matches your greetd config. `setup_greeter_system.sh` prints a ready-to-paste `config.toml` block with the path it finds. It also prepares `/var/lib/noctalia-greeter/` for that account.

Optional default session (must match a name from the session picker, e.g. `niri`):

```toml
command = "/usr/bin/noctalia-greeter-session -- --session niri"
```

List valid session names:

```sh
noctalia-greeter sessions
```

Sessions come from `wayland-sessions` `.desktop` files under `/usr/share`, each path in `XDG_DATA_DIRS`, and on NixOS `/run/current-system/sw/share`.

### Multi-monitor

By default the greeter is **mirrored on every connected monitor** (same UI on each display, sized to the primary output). To pin it to a single connector, set `output` in `/var/lib/noctalia-greeter/greeter.conf`:

```ini
output="DP-2"
```

The compositor disables the other connectors at the KMS level when `output` is set. If `output` names a disconnected connector, the greeter falls back to mirroring on all outputs.

When using multiple monitors, set `output_layout` manually or sync from Noctalia Shell (see Matching Noctalia Shell). Without it, outputs are placed left-to-right by connector name. List connector names with `noctalia-greeter outputs`:

```ini
output_layout="DP-1:0,0; HDMI-A-1:1920,0; DP-2:3840,0"
```

Coordinates are logical pixels from your desktop compositor. The greeter uses them for **order and row grouping**, then places outputs edge-to-edge at its own scale so the cursor can move between monitors.

Test locally with:

```sh
just run
```

On high-DPI panels (for example 4K), the greeter compositor applies fractional output scaling from the monitor's physical size when EDID reports it, otherwise from resolution. Scale is capped at 2×. The greeter client lays out at logical size and renders HiDPI buffers via Wayland fractional scale.

To override auto scaling, set `scale` in `greeter.conf` (read by the compositor):

```ini
scale=1.5
```

If `scale` is missing or invalid, the compositor falls back to auto scaling.

List connector names from a running Wayland session:

```sh
noctalia-greeter outputs
```

Restart greetd:

```sh
sudo systemctl restart greetd
```

On runit:

```sh
sudo sv restart greetd
```

Create log files once if needed:

```sh
just setup-log-dir
```

Logs: `/var/log/noctalia-greeter.log` and `/var/lib/noctalia-greeter/greeter.log`.

## Matching Noctalia Shell

With [Noctalia v5](https://github.com/noctalia-dev/noctalia) installed, open **Settings → Shell → Security → Noctalia Greeter → Sync Now**. The shell copies your wallpaper, palette, and multi-monitor layout (when available) to the greeter (you may be prompted for admin credentials). 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`.

Admin-only keys in `greeter.conf` (set by you, not the UI):

- `default_session` - session selected when the greeter opens (overrides last-used unless you pass `--session` on the command line)
- `default_user` - username to select on startup; opens the password step immediately (overrides user picker unless you go back; `--user` on the command line wins)
- `greeter_user` - greetd account name (setup/logging)
- `output` - Wayland connector name (see Multi-monitor)
- `output_layout` - multi-monitor positions as `NAME:X,Y; ...` in logical pixels (see Multi-monitor)
- `scale` - manual compositor scale factor (e.g. `1.5`); invalid or missing → auto scale
- `cursor_theme` - cursor theme name (e.g. `Adwaita`); missing → wlroots default cursor
- `cursor_size` - cursor size in pixels (e.g. `24`); missing → `24`
- `cursor_path` - colon-separated theme search path (sets `XCURSOR_PATH`); needed when the theme is not on the default search path (`~/.icons:/usr/share/icons:/usr/share/pixmaps`)
- `keyboard_layout` - XKB layout code(s), e.g. `cz`, `us`, `de,cz` (comma-separated for multiple layouts)
- `keyboard_variant` - XKB variant(s), e.g. `qwertz` (optional; comma-separated when multiple layouts)
- `keyboard_options` - XKB options string, e.g. `grp:alt_shift_toggle` (optional)

The greeter updates `session` and `scheme` when you change them in the UI.

## Cursor theme

The compositor resolves the cursor theme, size and search path in this order:

1. `cursor_theme` / `cursor_size` / `cursor_path` in `greeter.conf` (above)
2. The `XCURSOR_THEME`, `XCURSOR_SIZE` and `XCURSOR_PATH` environment variables
3. The wlroots defaults (built-in cursor at size `24`)

greetd starts greeters with an empty environment, so to use the environment
variables set them in the greetd session **command** rather than the service
environment, for example in `/etc/greetd/config.toml`:

```toml
[default_session]
command = "env XCURSOR_THEME=Adwaita XCURSOR_SIZE=24 /usr/bin/noctalia-greeter-session"
```

If the theme is not under the default search path, also set
`XCURSOR_PATH` (or `cursor_path`) to the directory that contains it. On NixOS,
use the `programs.noctalia-greeter.settings.cursor` options instead, which wire this up
for you.

## Keyboard

The greeter works without a mouse.

### Layout

The compositor builds an XKB keymap in this precedence order:

1. `greeter.conf`: `keyboard_layout` / `keyboard_variant` / `keyboard_options`
2. `XKB_DEFAULT_LAYOUT` / `XKB_DEFAULT_VARIANT` / `XKB_DEFAULT_OPTIONS` (environment)
3. The system default keymap

Example:

```ini
keyboard_layout = cz
```

Multiple layouts:

```ini
keyboard_layout = us,cz
keyboard_options = grp:alt_shift_toggle
```

Use standard [XKB layout codes](https://www.freedesktop.org/wiki/Software/XKeyboard-config/Rules/) (`de`, `fr`, `ru`, …).

greetd starts greeters with an empty environment, so set layout in `greeter.conf` or prefix the greetd session command:

```toml
[default_session]
command = "env XKB_DEFAULT_LAYOUT=cz /usr/bin/noctalia-greeter-session"
```

### Shortcuts

| 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`. Run `just setup-log-dir` if they are missing.
- **`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** - logs survive under `/var/log/noctalia-greeter.log` and `/var/lib/noctalia-greeter/greeter.log` (run `just setup-log-dir` once). Session output also goes there when writable.
- **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 shell v5 and greeter; run **Sync Now** in shell settings again; restart greetd or log out once.

Stuck display over SSH:

```sh
just recover
```

---

## Scope

Noctalia Greeter is a **display/login greeter** for greetd. It handles user/session selection and authentication UI.

It is **not** a desktop shell or compositor replacement.

---

## 🤝 Contributing

Contributions are welcome: fixes, polish, docs, or UX improvements.

- Open an issue for bugs and regressions
- Open a PR for improvements

---

## License

Distributed under the MIT License. See [LICENSE](LICENSE) for details.

ecosyste.ms

Data

Tools

Indexes

Applications

Experiments

Awesome

https://github.com/noctalia-dev/noctalia-greeter

Awesome Lists containing this project

README