v5-getting-started-nixos.md
Noctalia v5 can be installed both with and without flakes. As of writing, noctalia v5 does not yet exist in nixpkgs, meaning you will have to compile from source or use the binary cache.
To install Noctalia v5, first add the input using your preferred input-pinning method. Then you can install the package directly or use either the NixOS, Home Manager, or Hjem module.
Section titled “Adding the input”
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 }; };}
Add Noctalia to your tack inputs:
tack add noctalia github:noctalia-dev/noctalia
If you want to use the cache, make sure to disable any sort of following for Noctalia’s nixpkgs input.
Add Noctalia to your npins sources:
npins add github noctalia-dev noctalia --branch main
configuration.nix
{ pkgs, ... }:let noctalia = import (import ./npins).noctalia { inherit pkgs; # this line is optional, prevents downloading two versions of nixpkgs but disables cache };in # see installation below
Add Noctalia directly using builtins.fetchTarball. With pinning:
configuration.nix
{ pkgs, ... }:let noctalia-src = let commit = ""; # replace this with an actual commit id or tag in fetchTarball { url = "https://github.com/noctalia-dev/noctalia/archive/${commit}.tar.gz"; sha256 = ""; # replace this with hash from nix build output, or by using `nix-prefetch-url --unpack` };
noctalia = import noctalia-src { inherit pkgs; # this line is optional, prevents downloading two versions of nixpkgs but disables cache };in # see installation below
Without pinning (not recommended):
configuration.nix
{ pkgs, ... }:let noctalia-src = fetchTarball "https://github.com/noctalia-dev/noctalia/archive/main.tar.gz";
noctalia = import noctalia-src { inherit pkgs; # this line is optional, prevents downloading two versions of nixpkgs but disables cache };in # see installation below
Section titled “Installing the Package”
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];}
configuration.nix
let # see adding the input abovein { environment.systemPackages = [noctalia.package];}
Section titled “Home Manager Module”
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"; }; }; }; };}
let # see adding the input abovein { home-manager.users.drfoobar = { imports = [noctalia.homeModule];
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"; }; }; }; };}
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 = { ... }; }; }; };}
let # see adding the input abovein { hjem = { extraModules = [noctalia.hjemModule];
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; };}
let # see adding the input abovein { imports = [noctalia.nixosModule];
programs.noctalia = { enable = true;
# Enables NetworkManager, Bluetooth, UPower, and a power profile service. recommendedServices.enable = true; };}
Section titled “Systemd Service”
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="];};
nixConfig = { extra-substituters = ["https://noctalia.cachix.org"]; extra-trusted-public-keys = ["noctalia.cachix.org-1:pCOR47nnMEo5thcxNDtzWpOxNFQsBRglJzxWPp3dkU4="];};
extra-substituters = https://noctalia.cachix.orgextra-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";
tack add noctalia github:noctalia-dev/noctalia/cachix
npins add github noctalia-dev noctalia --branch cachix
Make sure not to update your tarball to a commit earlier than the latest commit on the cachix branch.