NixOS

Installation

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.

Adding the input

Add Noctalia to your flake inputs:

{
  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

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

{ 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):

{ 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

Installing the Package

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

flakes/tack
npins/tarball

Add the package to your system packages or equivalent:

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

let
  # see adding the input above
in {
  environment.systemPackages = [
    noctalia.package
  ];
}

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.

flakes/tack
npins/tarball

{ 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 above
in {
  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";
        };
      };
    };
  };
}

Hjem Module

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

flakes/tack
npins/tarball

{ inputs, ... }:
{
  hjem = {
    extraModules = [
      inputs.noctalia.hjemModules.default
    ];

    users.drfoobar = {
      programs.noctalia = {
        enable = true;

        settings = { ... };
      };
    };
  };
}

let
  # see adding the input above
in {
  hjem = {
    extraModules = [
      noctalia.hjemModule
    ];

    users.drfoobar = {
      programs.noctalia = {
        enable = true;

        settings = { ... };
      };
    };
  };
}

NixOS Module

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

flakes/tack
npins/tarball

{ 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 above
in {
  imports = [
    noctalia.nixosModule
  ];

  programs.noctalia = {
    enable = true;

    # Enables NetworkManager, Bluetooth, UPower, and a power profile service.
    recommendedServices.enable = true;
  };
}

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.

Binary Cache

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.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";

tack add noctalia github:noctalia-dev/noctalia/cachix

npins add github noctalia-dev noctalia --branch cachix