nh (Yet Another Nix Helper)

NH supports remote deployments using two primary flags to control where work happens:

• --build-host X: The host where the configuration is built (via nix copy + nix build).
• --target-host Y: The host where the result is deployed and activated.

Note: Derivation evaluation always happens locally. If --target-host is provided without --hostname or -H, the hostname defaults to the value in --target-host.

You can install or try NH using nix shell. Use the stable version from nixpkgs for most use cases, or the development version from the GitHub flake for the latest features.

nix shell nixpkgs#nh # stable
nix shell github:nix-community/nh # dev

To allow NH to detect and run the proper activation script for a NixOS specialisation, you must write the name of the specialisation to /etc/specialisation.

Example configuration:

{config, pkgs, ...}: {
  specialisation."foo".configuration = {
    environment.etc."specialisation".text = "foo";
    # ..rest of config
  };

  specialisation."bar".configuration = {
    environment.etc."specialisation".text = "bar";
    # ..rest of config
  };
}

NH supports both Nix flakes and classical NixOS configurations (channels/manual pinning).

• For Flakes: Use nh os switch /path/to/flake.
• For Classical Configurations:
  • Use nh os switch -f '<nixpkgs/nixos>'.
  • If your configuration is in a non-default location, use: nh os switch -f '<nixpkgs/nixos>' -- -I nixos-config=/path/to/configuration.nix.

Refer to nh os --help or man 1 nh for more details and environment variable defaults.

To enable specialisation detection for Home Manager, write the specialisation name to ~/.local/share/home-manager/specialisation.

Example configuration:

{config, pkgs, ...}: {
  specialisation."foo".configuration = {
    xdg.dataFile."home-manager/specialisation".text = "foo";
    # ..rest of config
  };

  specialisation."bar".configuration = {
    xdg.dataFile."home-manager/specialisation".text = "bar";
    # ..rest of config
  };
}

NH provides a NixOS module that allows you to integrate nh clean as a service. This is useful for automated garbage collection. You can specify retention policies via clean.extraArgs and point to your configuration flake via flake (which sets the NH_OS_FLAKE environment variable).

{
  programs.nh = {
    enable = true;
    clean.enable = true;
    clean.extraArgs = "--keep-since 4d --keep 3";
    flake = "/home/user/my-nixos-config"; # sets NH_OS_FLAKE variable for you
  };
}

Use the following environment variables to control remote deployment behavior:

• NH_REMOTE_CLEANUP: When set to 1, true, or yes, nh attempts to terminate remote Nix processes using pkill if you press Ctrl+C. This is opt-in and depends on pkill being available on the remote host.
• NH_NO_VALIDATE: When set to 1, skips pre-activation system validation checks. This is useful when the target host's store path is not accessible from the local machine (e.g., when building remotely and deploying to a different target).
• NH_SSHOPTS: Passes additional SSH options to the connection. Takes precedence over NIX_SSHOPTS.

# Enable remote cleanup
export NH_REMOTE_CLEANUP=1
nh os switch --build-host user@buildserver

# Skip validation for remote-to-remote deployments
export NH_NO_VALIDATE=1
nh os switch --build-host user@buildserver --target-host user@production

The nh search command allows you to search for Nix packages, NixOS/home-manager options, GitHub pull requests, and issues. You can use explicit subcommands or shorthand syntax.

Search Modes

• Packages: Search for Nix packages via search.nixos.org.
• Options: Search for NixOS or home-manager options via search.nixos.org.
• Offline: Search local SPAM database files without network access.
• Prs: Search Nixpkgs pull requests.
• Issues: Search Nixpkgs issues.

Shorthand Usage

You can omit the subcommand if you provide a query. The mode is determined by the --default-search flag (defaults to packages).

# Search for packages (default)
nh search hello

# Search for options using shorthand
nh search --default-search options hello

To avoid deprecation warnings, use the NH_FLAKE environment variable to specify your flake path. You can also use more specific variables to avoid global overrides:

• NH_OS_FLAKE (for OS-specific commands)
• NH_HOME_FLAKE (for Home Manager commands)
• NH_DARWIN_FLAKE (for Darwin commands)