Skip to content

NixOS

A Noctalia package is available on nixpkgs unstable.

If you’d prefer the latest git version or would like to use one of the modules, you can add the input using your preferred input-pinning method and optionally use the binary cache to avoid compiling locally.

Add Noctalia to your flake inputs:

flake.nix
{
inputs = {
noctalia = {
url = "github:noctalia-dev/noctalia";
inputs.nixpkgs.follows = "nixpkgs"; # this line is optional, prevents downloading two versions of nixpkgs but disables cache
};
};
}

Note that both the Home Manager and Hjem modules install the package for you, so you can omit this step.

Add the package to your system packages or equivalent:

configuration.nix
{ inputs, pkgs, ... }:
{
environment.systemPackages = [
inputs.noctalia.packages.${pkgs.stdenv.hostPlatform.system}.default
];
}

The Home Manager module allows you to configure Noctalia’s settings (that you would otherwise put in ~/.config/noctalia/) using nix instead of toml, or allows you to link an existing toml file. It is optional.

{ inputs, ... }:
{
home-manager.users.drfoobar = {
imports = [
inputs.noctalia.homeModules.default
];
programs.noctalia = {
enable = true;
settings = { # This may also be a string or path to a .toml file.
theme = {
mode = "dark";
source = "builtin";
builtin = "Catppuccin";
};
wallpaper = {
enabled = true;
default.path = "/path/to/wallpapers/wallpaper.png";
};
};
};
};
}

Pin a plugin repository alongside Noctalia. The official plugin repository contains plugin sources without a flake.nix, so set flake = false. Nix still records its revision and content hash in flake.lock:

inputs.noctalia-plugins = {
url = "github:noctalia-dev/official-plugins";
flake = false;
};

Use it as a read-only path source in the Home Manager module. Plugin versions then follow your flake.lock, including updates and rollbacks:

{ inputs, pkgs, ... }:
{
imports = [ inputs.noctalia.homeModules.default ];
programs.noctalia = {
enable = true;
extraPackages = [ pkgs.gpu-screen-recorder pkgs.slurp ];
settings = {
plugins = {
enabled = [ "noctalia/screen_recorder" ];
source = [
{
name = "official";
kind = "path";
location = "${inputs.noctalia-plugins}";
enabled = true;
}
];
};
plugin_settings."noctalia/screen_recorder" = {
frame_rate = 30;
show_cursor = false;
};
};
};
}

An explicit plugins.source list replaces the default sources. Noctalia reads path sources directly and never updates their contents. Choose plugin revisions compatible with your Noctalia version.

The Home Manager module’s programs.noctalia.extraPackages option adds executables to Noctalia’s PATH, including when launched by systemd or through the desktop launcher. It wraps the selected programs.noctalia.package without rebuilding Noctalia and requires that package to be non-null. List the packages required by your plugins; dependencies are not installed automatically from plugin manifests.

Plugin settings use the keys declared in each plugin’s plugin.toml. Runtime changes in Settings take precedence over the declarative defaults; see Plugin settings.

For those using Hjem instead of Home Manager, a Hjem module is also available.

{ inputs, ... }:
{
hjem = {
extraModules = [
inputs.noctalia.hjemModules.default
];
users.drfoobar = {
programs.noctalia = {
enable = true;
settings = { ... };
};
};
};
}

The NixOS module installs the package system-wide and can enable some recommended services.

{ inputs, ... }:
{
imports = [
inputs.noctalia.nixosModules.default
];
programs.noctalia = {
enable = true;
# Enables NetworkManager, Bluetooth, UPower, and a power profile service.
recommendedServices.enable = true;
};
}

Each of the above modules includes a systemd user service for Noctalia, which can be enabled by setting programs.noctalia.systemd.enable = true.

Pre-built binaries are available on Cachix, so you can skip compiling locally.

You can configure the substituter either in your NixOS config, flake, or /etc/nix/nix.conf:

You can add the cache either to your flake, nixos configuration, or /etc/nix/nix.conf.

nix.settings = {
extra-substituters = [ "https://noctalia.cachix.org" ];
extra-trusted-public-keys = [ "noctalia.cachix.org-1:pCOR47nnMEo5thcxNDtzWpOxNFQsBRglJzxWPp3dkU4=" ];
};

Overriding any of Noctalia’s inputs (e.g. via inputs.nixpkgs.follows with flakes) changes the derivation hash, causing cache misses.

Additionally, tracking main directly may pull in a commit that hasn’t been cached yet by CI.

To avoid this, the cachix branch always points to the latest cached commit. Pinning to this branch guarantees you always track the latest commit that has already been cached:

noctalia.url = "github:noctalia-dev/noctalia/cachix";