How configuration works

Noctalia can be configured in two ways: files you write yourself, and settings the app saves for you.

For most people, the important rule is simple: put your own configuration in ~/.config/noctalia/. If something changed in the GUI and now seems to ignore your file, check ~/.local/state/noctalia/settings.toml.

The two layers

Your hand-written config lives in:

• $XDG_CONFIG_HOME/noctalia/
• or ~/.config/noctalia/

Noctalia reads every *.toml file in that folder, sorts them alphabetically, and merges them into one config. A single config.toml is the easiest setup:

~/.config/noctalia/config.toml

[theme]
mode = "dark"

[bar.main]
position = "top"

You can also split things up if you like tidy dotfiles:

~/.config/noctalia/
├── bar.toml
├── theme.toml
└── widgets.toml

GUI-managed overrides live in:

• $XDG_STATE_HOME/noctalia/settings.toml
• or ~/.local/state/noctalia/settings.toml

Noctalia writes this file when you change settings through the UI, setup flows, IPC-backed controls, and other runtime actions that need to persist.

Which value wins?

Noctalia loads configuration in this order:

1. Built-in defaults
2. Your *.toml files in ~/.config/noctalia/
3. GUI-managed overrides in ~/.local/state/noctalia/settings.toml

Because ~/.local/state/noctalia/settings.toml loads last, it wins when it contains the same setting as your config file. When Settings writes a value that matches the parsed value from the lower layers, Noctalia removes that redundant key instead of keeping it as a GUI override.

Tip

If you are confused about why a value from config.toml is not taking effect, inspect or temporarily move ~/.local/state/noctalia/settings.toml.

Where should I edit?

Use ~/.config/noctalia/ for curated config: the things you want to keep in dotfiles, copy to another machine, or manage declaratively.

Treat ~/.local/state/noctalia/settings.toml as an app-managed override file. It is useful to inspect when debugging GUI changes, and safe to delete when you want to clear those overrides. Keeping it outside ~/.config also lets the GUI save changes when your config directory is read-only, for example on NixOS.

Both layers are watched for changes and hot-reloaded. If neither layer exists, Noctalia uses its built-in defaults.

Where next?

• Shell covers global behavior like fonts, scale, shadows, OSD, keybinds, and hooks.
• Bars and Widgets cover the top or side bar and everything inside it.
• Dock covers the optional app dock.
• Theme and Theming templates cover colors and generated app themes.
• Wallpaper & backdrop covers wallpapers, per-monitor folders, automation, and overview backdrop.
• Services covers audio, brightness, night light, weather, idle, and notifications.
• IPC lists commands for keybinds, scripts, automation, and hooks.