nathan/home-manager

Fork 0

mirror of https://github.com/nix-community/home-manager.git synced 2026-06-05 21:02:51 +00:00

Files

Austin Horstman 7d8127d308 flake: track nixpkgs-unstable

2026-05-29 19:01:27 -05:00

6.0 KiB

Raw Blame History

Upgrading to a new Home Manager release

Overview

When moving your configuration to a new Nixpkgs release branch, you should also move Home Manager to the matching release branch. On NixOS this usually means upgrading Home Manager together with NixOS. On standalone and nix-darwin installations, match Home Manager to the Nixpkgs branch used by your configuration. The examples below use 25.11; replace this with the release branch you are upgrading to.

If your configuration follows nixos-unstable or nixpkgs-unstable, use Home Manager's master branch.

Understanding Home Manager Versioning

Home Manager follows NixOS release cycles and provides corresponding branches:

release-: Stable branch for the matching NixOS or Nixpkgs release, such as release-25.11.
master: Development branch (tracks nixpkgs-unstable)

:::{.note} Use the Home Manager branch that matches the Nixpkgs branch used to evaluate your Home Manager configuration. For stable NixOS configurations, this is normally the same as your NixOS version. :::

Flake-Based Installation

If you are using Home Manager with Nix flakes, update your nixpkgs and home-manager inputs together:

{
  description = "Home Manager configuration";

  inputs = {
    # Match the Nixpkgs branch to the release you are using.
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-25.11";

    home-manager = {
      # Match the Home Manager branch to the Nixpkgs branch above.
      url = "github:nix-community/home-manager/release-25.11";
    };
  };

  outputs = { nixpkgs, home-manager, ... }: {
    homeConfigurations."yourusername" = home-manager.lib.homeManagerConfiguration {
      pkgs = nixpkgs.legacyPackages.x86_64-linux;
      modules = [ ./home.nix ];
    };
  };
}

For nixos-unstable or nixpkgs-unstable, use the master branch instead:

{
  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixpkgs-unstable";

    home-manager = {
      url = "github:nix-community/home-manager";
    };
  };
}

Then update the lock file and rebuild using the command for your installation method.

For a standalone Home Manager flake:

$ nix flake update
$ home-manager switch --flake .

For Home Manager as a NixOS module:

$ nix flake update
$ sudo nixos-rebuild switch --flake .

For Home Manager as a nix-darwin module:

$ nix flake update
$ darwin-rebuild switch --flake .

These commands assume that your current directory is the flake. If not, pass the flake path or URI with --flake <flake-uri>.

Channel-Based Installation

For a standalone channel-based installation, first verify your current Home Manager channel:

$ nix-channel --list

The entry identifies the Home Manager branch currently in use. For example:

home-manager https://github.com/nix-community/home-manager/archive/release-25.11.tar.gz

Update the Home Manager channel to the branch matching your Nixpkgs release, then switch:

$ nix-channel --add https://github.com/nix-community/home-manager/archive/release-25.11.tar.gz home-manager
$ nix-channel --update
$ home-manager switch

When Home Manager is installed as a NixOS module with channels, update the root user's Home Manager channel and rebuild the system:

$ sudo nix-channel --add https://github.com/nix-community/home-manager/archive/release-25.11.tar.gz home-manager
$ sudo nix-channel --update
$ sudo nixos-rebuild switch

When Home Manager is installed as a nix-darwin module with channels, update the Home Manager channel used by your nix-darwin configuration and rebuild the system:

$ nix-channel --add https://github.com/nix-community/home-manager/archive/release-25.11.tar.gz home-manager
$ nix-channel --update
$ darwin-rebuild switch

State Version Management

:::{.warning} Careful updating your home.stateVersion when upgrading Home Manager. :::

The stateVersion should remain set to the Home Manager release you first used for this home configuration.

{
  # Example: if this home configuration was first created on 24.11.
  home.stateVersion = "24.11";
}

Why? The stateVersion ensures backward compatibility and prevents breaking changes from affecting your existing configuration.

Remember: Channel or flake input version is not the same as state version. Update Home Manager, keep home.stateVersion unchanged, and only change it after reading the release notes and migrating any affected configuration.

Troubleshooting

Common Issues

Check the Home Manager Release Notes for breaking changes.

Version Mismatch Warning: If you see warnings about version mismatches, ensure your Home Manager branch matches the Nixpkgs branch used by your configuration. For NixOS stable releases, this usually means matching your NixOS version.
Module Changes: Modules are constantly being updated with new features to keep up with changes in upstream packaging or to fix bugs and add features. If you have an unexpected change, check if there was something noted in the release notes or news entries.
Channel Not Found: If nix-channel --list shows no channels, you might be using a different installation method, such as flakes, or Home Manager may be imported through your system configuration.

Verification

After upgrading, verify the installation:

$ home-manager --version

This should show the Home Manager version or indicate that it is using the expected release branch.

6.0 KiB Raw Blame History