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

⭐28stars🔀1forks📁View on GitHub🕐Updated Jan 2, 2026⬇️6downloads

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.
nameupgrade-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

  1. Check current state

    nixos-version
    nix --version
    
  2. Identify 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)
  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):

    # Edit 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:

    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:

sudo nixos-rebuild switch --rollback
git checkout flake.nix flake.lock

$ARGUMENTS