hnm — HackerOS Nix Manager

Overview #

HNM gives you access to the entire nixpkgs repository (~100 000 packages) without having to manage Nix flakes, NixOS modules, or configuration.nix. It works identically to how Flox uses Nix under the hood — a dedicated nix-env profile at ~/.hnm/profile.

Quickstart #

# Search for a package
$ hnm search ripgrep

# Install packages
$ hnm install ripgrep bat htop

# Show information about a package
$ hnm info ripgrep

# List installed packages
$ hnm list

# Update everything
$ hnm update

# Remove a package
$ hnm remove htop

# Check Nix installation
$ hnm check

# Run full diagnostics
$ hnm doctor

Command Reference #

Package commands

System commands

Command aliases

Search & Install #

Searching

hnm search runs nix search nixpkgs <query> and displays results in a formatted table. Installed packages are marked with a ✓.

# Basic search
$ hnm search ripgrep

# JSON output (useful for scripting)
$ hnm search ripgrep --json

Installing

hnm install resolves the package in nixpkgs, installs it into ~/.hnm/profile via nix-env, and records it in the HNM state file. Multiple packages can be installed in one command.

# Install a single package
$ hnm install ripgrep

# Install multiple packages at once
$ hnm install ripgrep bat htop neovim fd

# Install without activating profile (advanced)
$ hnm install ripgrep --no-env

Updating Packages #

hnm update runs two steps: first it refreshes the nixpkgs channel (nix-channel --update), then upgrades all installed packages (nix-env --upgrade).

# Update everything
$ hnm update

# Update specific packages only
$ hnm update ripgrep bat

Pinning #

Pinning records a specific version in the HNM state file and marks the package so you know it should not be changed automatically.

# Pin at the currently installed version
$ hnm pin ripgrep

# Pin at a specific version
$ hnm pin ripgrep 14.0.0

# Remove the pin
$ hnm unpin ripgrep

Pinned packages appear in hnm list with a [pinned: x.x.x] annotation.

Generations & Rollback #

Every install, remove, or upgrade in nix-env creates a new generation — a snapshot of the profile state. HNM exposes this through hnm rollback.

# Roll back to the previous generation
$ hnm rollback

# Roll back to a specific generation number
$ hnm rollback 3

# The rollback command shows available generations first:
  gen    1   2024-12-01
  gen    2   2025-01-15
  gen    3   2025-03-22  ← current

Progress & Logs #

HNM uses a combined progress display: scrolling log lines above a live progress bar with a spinner, percentage, and current action label. Stderr from Nix commands is shown inline as error lines.

The spinner cycles through / → - → \ → |. Log lines scroll above the bar and are preserved in the terminal history once the operation completes.

Color Scheme #

Doctor #

hnm doctor runs a full health check of your HNM and Nix setup. It checks for required binaries, Nix channels, the HNM profile directory, the Nix store, state and config files, and PATH configuration.

$ hnm doctor

  ▸ HNM Doctor — system diagnostics
  ──────────────────────────────────────────────────
  ✓ nix             nix (Nix) 2.18.4
  ✓ nix-env         nix-env (Nix) 2.18.4
  ✓ nix-channel     nix-channel (Nix) 2.18.4
  ✓ nix-store       nix-store (Nix) 2.18.4

  ✓ channels        nixpkgs https://nixos.org/channels/nixpkgs-unstable
  ✓ profile         /home/user/.hnm/profile
  ✓ /nix/store      exists  (4.2G)

  ✓ state           12 package(s) tracked
  ✓ config          channel = https://nixos.org/channels/nixpkgs-unstable

  ✓ PATH            contains .nix-profile

  ✓ all checks passed — HNM is healthy

Environment #

HNM packages are installed into ~/.hnm/profile/bin. To use them in your shell, add the profile to your PATH.

# Print the snippet to add to your shell rc
$ hnm env activate

# Check current status
$ hnm env status

# Print removal instructions
$ hnm env deactivate

Add to your ~/.bashrc or ~/.zshrc:

# HNM profile
export PATH="$HOME/.hnm/profile/bin:$PATH"
[ -f ~/.nix-profile/etc/profile.d/nix.sh ] && \
    . ~/.nix-profile/etc/profile.d/nix.sh

Garbage Collection #

Nix keeps every version of every package in /nix/store. Over time this can grow large. Run hnm gc to collect unreachable store paths.

$ hnm gc

  ▸ Nix garbage collection
  ────────────────────────────────
       store size before   4.2G

  │ nix-store --gc
  │ finding garbage collector roots...
  │ deleting garbage...
  │ deleting '/nix/store/old-path-xyz'
  │ ...
  /  [████████████████████████████████████████]  100%  ✓ garbage collection complete

       store size after    2.1G
  ✓ done

Clean Cache #

hnm clean removes HNM's own download cache and the Nix evaluation cache. It does not touch the Nix store — use hnm gc for that.

$ hnm clean

  ✓ removed ~/.cache/hnm   (128 MB)
  ✓ removed nix eval cache  (44 MB)

  ✓ freed 172 MB
  To free Nix store space, run:  hnm gc

Auto Nix Bootstrap #

Every command that requires Nix (install, remove, search, update, gc, etc.) checks whether Nix is present before running. If Nix is missing, HNM automatically runs hnm unpack to bootstrap it — no manual action required.

# Manually bootstrap Nix
$ hnm unpack

# This runs:
#   sh <(curl -L https://nixos.org/nix/install) --no-daemon
#   . ~/.nix-profile/etc/profile.d/nix.sh
#   nix-channel --add https://nixos.org/channels/nixpkgs-unstable nixpkgs
#   nix-channel --update

Configuration #

HNM stores its configuration in ~/.config/hnm/config.toml. The file is created automatically on first run with sensible defaults.

# ~/.config/hnm/config.toml

nix_channel      = "https://nixos.org/channels/nixpkgs-unstable"
profile_dir      = "/home/user/.hnm/profile"
auto_gc          = false
max_generations  = 10

State File #

HNM tracks installed packages in ~/.local/share/hnm/state.json. This is separate from the Nix profile itself and records HNM-specific metadata such as install timestamps, descriptions, and pins.

{
  "installed": {
    "ripgrep": {
      "name":         "ripgrep",
      "version":      "14.1.1",
      "attr_path":    "nixpkgs#ripgrep",
      "installed_at": "2025-04-17T10:32:00Z",
      "pinned":       null,
      "description": "Fast grep alternative written in Rust"
    }
  },
  "generation":   4,
  "last_update":  "2025-04-17T10:35:00Z"
}

HNM vs Flox #