# Richardgill Nix Upgrade Nixos

> Upgrade NixOS Release

- Skill: `tomevault-io/richardgill-nix-upgrade-nixos` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/richardgill-nix-upgrade-nixos`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/richardgill-nix-upgrade-nixos/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/richardgill-nix-upgrade-nixos

---


# Upgrade NixOS Release

Upgrade NixOS to a new stable release version. This involves updating version-pinned flake inputs and handling any breaking changes.

## Process

1. **Check current state**
   ```bash
   nixos-version
   nix --version
   ```

2. **Identify version-pinned inputs in flake/flake.nix** that need updating:
   - `nixpkgs` (e.g., `nixos-25.05` → `nixos-25.11`)
   - `home-manager` (e.g., `release-25.05` → `release-25.11`)
   - `nix-darwin` (e.g., `nix-darwin-25.05` → `nix-darwin-25.11`)
   - `stylix` (e.g., `release-25.05` → `release-25.11`)

3. **Research the target release**
   - Use web search to find the latest stable NixOS release
   - Check release notes for breaking changes relevant to this config
   - Verify release branches exist for home-manager, stylix, nix-darwin

4. **Identify breaking changes** that affect this config:
   - Scan modules for services/packages that might be affected
   - Key areas: Hyprland, Docker, Steam, Secure Boot, impermanence

5. **Create upgrade plan** (use creating-plans skill):
   - Save to `thoughts/shared/issues/NN-nixos-<version>-upgrade/plan.md`
   - Include exact file changes with line numbers
   - Include verification commands
   - Include rollback instructions

6. **Execute upgrade** (when user is ready):
   ```bash
   # Edit flake/flake.nix with new versions
   just update        # Update flake.lock
   just check         # Build without applying (safe)
   just switch        # Apply the upgrade
   ```

7. **Post-upgrade verification**:
   ```bash
   nixos-version
   nix --version
   docker --version
   systemctl status docker tailscaled
   hyprctl version
   ```

## What stays pinned (don't change)

- `lanzaboote` - explicit version pin (e.g., v0.4.2), not tied to NixOS releases
- `nixpkgs-unstable` - always tracks unstable
- Inputs that `follow` nixpkgs - automatically updated

## Rollback
Print out the instructions to:
```bash
sudo nixos-rebuild switch --rollback
git checkout flake/flake.nix flake/flake.lock
```

$ARGUMENTS

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/richardgill) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-11 -->