upgrade-nixos
Upgrade NixOS to a new release version (e.g., 25.05 → 25.11) - researches breaking changes, updates flake inputs, and guides through the upgrade process
When & Why to Use This Skill
This Claude skill automates the complex process of upgrading NixOS to new stable release versions. It streamlines system maintenance by researching breaking changes, updating version-pinned flake inputs (such as nixpkgs, home-manager, and nix-darwin), and generating a comprehensive upgrade plan. By providing structured verification steps and rollback instructions, it ensures a safe and reliable transition between NixOS distributions.
Use Cases
- Major Release Migration: Seamlessly transition your NixOS system from one stable release to the next (e.g., 25.05 to 25.11) while ensuring all flake inputs are synchronized to the correct branches.
- Breaking Change Mitigation: Proactively identify and resolve configuration issues caused by deprecated modules or service changes in the target NixOS release through automated web research.
- System Maintenance Automation: Standardize the upgrade workflow for NixOS machines by generating documented plans that include pre-upgrade checks, execution commands, and post-upgrade verification.
| name | upgrade-nixos |
|---|---|
| description | | |
| Triggers | "upgrade nixos", "upgrade to new release", "update nixos version", |
Upgrade NixOS Release
Upgrade NixOS to a new stable release version. This involves updating version-pinned flake inputs and handling any breaking changes.
Process
Check current state
nixos-version nix --versionIdentify version-pinned inputs in 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)
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
Identify breaking changes that affect this config:
- Scan modules for services/packages that might be affected
- Key areas: Hyprland, Docker, Steam, Secure Boot, impermanence
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
- Save to
Execute upgrade (when user is ready):
# Edit flake.nix with new versions just update # Update flake.lock just check # Build without applying (safe) just switch # Apply the upgradePost-upgrade verification:
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 releasesnixpkgs-unstable- always tracks unstable- Inputs that
follownixpkgs - automatically updated
Rollback
Print out the instructions to:
sudo nixos-rebuild switch --rollback
git checkout flake.nix flake.lock
$ARGUMENTS