---

name: nixos description: NixOS and Nix flake development for multi-repo architectures, airgapped deployments, and K3s infrastructure. Use when working with flake.nix files, NixOS modules, derivations, devShells, overlays, OCI image packaging, or composing multiple flake repositories. Covers Nix language syntax, flake inputs/outputs, nixosModules exports, stdenv.mkDerivation, and home-manager integration.

NixOS Development

Overview

Build and maintain NixOS configurations using Nix flakes. Focus on multi-repo composition, airgapped deployments, and declarative infrastructure.

Quick Reference

| Task | Command | |------|---------| | Build package | nix build .#packageName | | Enter devShell | nix develop | | Update flake inputs | nix flake update | | Update single input | nix flake lock --update-input nixpkgs | | Show flake outputs | nix flake show | | Check flake | nix flake check | | Rebuild NixOS | sudo nixos-rebuild switch --flake .#hostname | | Build ISO | nix build .#nixosConfigurations.iso.config.system.build.isoImage |

Flake Structure

Standard multi-repo flake pattern:

{
  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";

    # Pin dependent flakes to same nixpkgs
    other-flake.url = "git+ssh://gitlab.example.com/repo";
    other-flake.inputs.nixpkgs.follows = "nixpkgs";
  };

  outputs = { self, nixpkgs, other-flake, ... }:
    let
      system = "x86_64-linux";
      pkgs = import nixpkgs { inherit system; };
    in {
      # NixOS system configurations
      nixosConfigurations.hostname = nixpkgs.lib.nixosSystem {
        inherit system;
        modules = [
          other-flake.nixosModules.default
          ./configuration.nix
        ];
      };

      # Reusable NixOS modules
      nixosModules.default = import ./modules;

      # Packages
      packages.${system} = { /* ... */ };

      # Development shells
      devShells.${system}.default = pkgs.mkShell { /* ... */ };
    };
}

NixOS Module Pattern

Export modules for composition:

# modules/default.nix
{ config, lib, pkgs, ... }:
{
  imports = [ ./service.nix ];

  options.myModule.enable = lib.mkEnableOption "my module";

  config = lib.mkIf config.myModule.enable {
    # configuration here
  };
}

OCI Image Packaging

For airgapped deployments, package images as store paths:

# Single image to OCI tarball
imagePackage = pkgs.runCommand "image-name" {
  buildInputs = [ pkgs.skopeo ];
} ''
  skopeo copy docker://registry/image:tag oci-archive:$out
'';

Helm + Kustomize in Nix

Render manifests at build time:

manifests = pkgs.runCommand "manifests" {
  buildInputs = [ pkgs.kubernetes-helm pkgs.kustomize ];
} ''
  helm template release ${./chart} --namespace ns > base.yaml
  kustomize build ${./overlays} > $out
'';

Detailed References

For comprehensive documentation on specific topics:

| Topic | Reference File | |-------|----------------| | Nix language syntax | references/nix-language.md | | Flake inputs/outputs | references/flakes.md | | NixOS modules & options | references/nixos-modules.md | | Packaging & derivations | references/packaging.md | | DevShells & overlays | references/devshells.md | | Home Manager | references/home-manager.md |

Common Patterns

Pin nixpkgs across repos

Use inputs.X.inputs.nixpkgs.follows = "nixpkgs" to ensure consistent package versions.

Conditional module loading

imports = lib.optionals config.feature.enable [ ./optional-module.nix ];

Lazy evaluation with mkIf

Always use lib.mkIf for conditional config to avoid infinite recursion:

config = lib.mkIf config.myService.enable { /* ... */ };

Override priorities

• lib.mkDefault (priority 1000) - easily overridable defaults
• lib.mkForce (priority 50) - force value regardless of other definitions
• lib.mkOverride N - custom priority (lower = higher priority)

Troubleshooting

"error: getting status of '/nix/store/...': No such file or directory"

Missing store path. Run nix build or ensure binary cache is configured.

"error: infinite recursion encountered"

Using config values in imports or not wrapping conditional config in lib.mkIf.

"error: attribute 'X' missing"

Check flake inputs match expected names. Verify follows directives.

Flake not seeing local changes

Run git add . - flakes ignore untracked files.