mirror of
https://github.com/nix-community/home-manager.git
synced 2026-06-05 21:02:51 +00:00
docs: clarify update and upgrade workflows
Describe update and release-upgrade workflows separately so users can tell when to update the current branch versus move to a new Home Manager release branch. Expand routine update instructions for flake users by explaining that flake inputs are pinned in flake.lock, showing all-input and selected-input update commands, and separating the rebuild command for standalone, NixOS module, and nix-darwin module installations. Keep channel instructions available for standalone and system-module users, including the different channel owner used by NixOS module setups. Also correct nix-darwin terminology in the installation and flakes docs so those sections do not use NixOS-specific wording.
This commit is contained in:
Austin Horstman
@@ -5,9 +5,9 @@ environments directly from the
|
||||
[nix-darwin](https://github.com/nix-darwin/nix-darwin/) configuration file,
|
||||
which often is more convenient than using the `home-manager` tool.
|
||||
|
||||
To make the NixOS module available for use you must `import` it into
|
||||
your system configuration. This is most conveniently done by adding a
|
||||
Home Manager channel. For example, if you are following Nixpkgs master
|
||||
To make the nix-darwin module available for use you must `import` it
|
||||
into your system configuration. This is most conveniently done by adding
|
||||
a Home Manager channel. For example, if you are following Nixpkgs master
|
||||
or an unstable channel, you can run
|
||||
|
||||
``` shell
|
||||
@@ -28,9 +28,9 @@ It is then possible to add
|
||||
imports = [ <home-manager/nix-darwin> ];
|
||||
```
|
||||
|
||||
to your nix-darwin `configuration.nix` file, which will introduce a new
|
||||
NixOS option called `home-manager` whose type is an attribute set that
|
||||
maps user names to Home Manager configurations.
|
||||
to your nix-darwin `configuration.nix` file, which will introduce a
|
||||
`home-manager.users` option whose type is an attribute set that maps
|
||||
user names to Home Manager configurations.
|
||||
|
||||
For example, a nix-darwin configuration may include the lines
|
||||
|
||||
|
||||
@@ -20,10 +20,32 @@ flake in three ways:
|
||||
`nixos-rebuild`. See [NixOS module](#sec-flakes-nixos-module) for a
|
||||
description of this setup.
|
||||
|
||||
3. This allows the user profiles to be built together with the system
|
||||
when running `darwin-rebuild`. See [nix-darwin
|
||||
module](#sec-flakes-nix-darwin-module) for a description of this
|
||||
setup.
|
||||
3. As a module within a [nix-darwin](https://github.com/nix-darwin/nix-darwin/)
|
||||
system configuration. This allows the user profiles to be built
|
||||
together with the system when running `darwin-rebuild`. See
|
||||
[nix-darwin module](#sec-flakes-nix-darwin-module) for a
|
||||
description of this setup.
|
||||
|
||||
Advanced users may want Home Manager's `nixpkgs` input to follow the
|
||||
same Nixpkgs input as the rest of their flake. This avoids a second
|
||||
Nixpkgs input and makes Home Manager use the same pinned Nixpkgs source
|
||||
revision as the rest of the configuration:
|
||||
|
||||
``` nix
|
||||
home-manager.inputs.nixpkgs.follows = "nixpkgs";
|
||||
```
|
||||
|
||||
This removes the compatibility assumption between Home Manager and the
|
||||
Nixpkgs revision in Home Manager's own lock file, so use it carefully,
|
||||
especially when tracking unstable branches.
|
||||
|
||||
This does not by itself make Home Manager use the same `pkgs` value as
|
||||
your NixOS or nix-darwin system. In NixOS and nix-darwin module setups,
|
||||
`home-manager.useGlobalPkgs = true` controls that behavior by making
|
||||
Home Manager modules receive the system `pkgs` value. When
|
||||
`home-manager.useGlobalPkgs` is enabled, configure Nixpkgs overlays and
|
||||
configuration at the system level instead of through Home Manager
|
||||
`nixpkgs.*` options.
|
||||
|
||||
```{=include=} sections
|
||||
nix-flakes/prerequisites.md
|
||||
@@ -32,5 +54,3 @@ nix-flakes/nixos.md
|
||||
nix-flakes/nix-darwin.md
|
||||
nix-flakes/flake-parts.md
|
||||
```
|
||||
|
||||
|
||||
|
||||
@@ -10,7 +10,6 @@ Manager's flake module, `flakeModules.home-manager`.
|
||||
inputs = {
|
||||
nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable";
|
||||
home-manager.url = "github:nix-community/home-manager";
|
||||
home-manager.inputs.nixpkgs.follows = "nixpkgs";
|
||||
flake-parts.url = "github:hercules-ci/flake-parts";
|
||||
};
|
||||
|
||||
|
||||
@@ -12,7 +12,6 @@ to that of NixOS. The `flake.nix` would be:
|
||||
darwin.url = "github:nix-darwin/nix-darwin";
|
||||
darwin.inputs.nixpkgs.follows = "nixpkgs";
|
||||
home-manager.url = "github:nix-community/home-manager";
|
||||
home-manager.inputs.nixpkgs.follows = "nixpkgs";
|
||||
};
|
||||
|
||||
outputs = inputs@{ nixpkgs, home-manager, darwin, ... }: {
|
||||
@@ -47,7 +46,7 @@ outside the module graph, such as flake inputs, prefer
|
||||
`home-manager.extraSpecialArgs`.
|
||||
|
||||
and it is also rebuilt with the nix-darwin generations. The rebuild
|
||||
command here may be `darwin-rebuild switch --flake <flake-uri>`.
|
||||
command here may be `darwin-rebuild switch --flake ~/.config/darwin`.
|
||||
|
||||
You can use the above `flake.nix` as a template in `~/.config/darwin` by
|
||||
|
||||
|
||||
@@ -10,7 +10,6 @@ be as follows:
|
||||
inputs = {
|
||||
nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable";
|
||||
home-manager.url = "github:nix-community/home-manager";
|
||||
home-manager.inputs.nixpkgs.follows = "nixpkgs";
|
||||
};
|
||||
|
||||
outputs = inputs@{ nixpkgs, home-manager, ... }: {
|
||||
@@ -47,7 +46,10 @@ outside the module graph, such as flake inputs, prefer
|
||||
The Home Manager configuration is then part of the NixOS configuration
|
||||
and is automatically rebuilt with the system when using the appropriate
|
||||
command for the system, such as
|
||||
`nixos-rebuild switch --flake <flake-uri>`.
|
||||
|
||||
``` shell
|
||||
$ nixos-rebuild switch --flake /etc/nixos
|
||||
```
|
||||
|
||||
You can use the above `flake.nix` as a template in `/etc/nixos` by
|
||||
|
||||
|
||||
@@ -29,7 +29,6 @@ imported Home Manager modules, use `extraSpecialArgs` in the call to
|
||||
inputs = {
|
||||
nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable";
|
||||
home-manager.url = "github:nix-community/home-manager";
|
||||
home-manager.inputs.nixpkgs.follows = "nixpkgs";
|
||||
};
|
||||
|
||||
outputs = inputs@{ nixpkgs, home-manager, ... }: {
|
||||
@@ -79,14 +78,13 @@ $ home-manager switch --flake ~/hmconf
|
||||
```
|
||||
|
||||
::: {.note}
|
||||
The flake inputs are not automatically updated by Home Manager. You need
|
||||
to use the standard `nix flake update` command for that.
|
||||
The flake inputs are not automatically updated by Home Manager. Update
|
||||
the lock file with `nix flake update` before switching if you want to
|
||||
use newer input revisions.
|
||||
|
||||
If you only want to update a single flake input, then the command
|
||||
`nix flake lock --update-input <input>` can be used.
|
||||
If you only want to update specific flake inputs, name them explicitly,
|
||||
for example `nix flake update nixpkgs home-manager`.
|
||||
|
||||
You can also pass flake-related options such as `--recreate-lock-file`
|
||||
or `--update-input <input>` to `home-manager` when building or
|
||||
switching, and these options will be forwarded to `nix build`. See the
|
||||
[NixOS Wiki page](https://wiki.nixos.org/wiki/Flakes) for details.
|
||||
These commands assume that your current directory is the flake. If not,
|
||||
pass the flake path or URI with `--flake <flake-uri>`.
|
||||
:::
|
||||
|
||||
@@ -1,8 +1,64 @@
|
||||
# Updating {#sec-updating}
|
||||
|
||||
If you have installed Home Manager using the Nix channel method then
|
||||
updating Home Manager is done by first updating the channel. You can
|
||||
then switch to the updated Home Manager environment.
|
||||
Updating means moving to a newer revision of the Home Manager branch
|
||||
that your configuration already follows. For example, a configuration
|
||||
using `release-25.11` can update to a newer revision of `release-25.11`
|
||||
without changing release branches.
|
||||
|
||||
If you want to move from one release branch to another, such as
|
||||
`release-25.05` to `release-25.11`, or between a release branch and
|
||||
`master`, see
|
||||
[Upgrading to a new Home Manager release](#sec-upgrade-release).
|
||||
|
||||
## Flake-Based Configurations {#sec-updating-flakes}
|
||||
|
||||
Flake inputs are pinned in `flake.lock`, and Home Manager will keep using
|
||||
the pinned revisions until you update that lock file.
|
||||
|
||||
To update all inputs in the flake:
|
||||
|
||||
``` shell
|
||||
$ nix flake update
|
||||
```
|
||||
|
||||
To update only specific inputs, name them explicitly:
|
||||
|
||||
``` shell
|
||||
$ nix flake update home-manager nixpkgs
|
||||
```
|
||||
|
||||
These commands assume that your current directory is the flake. If not,
|
||||
pass the flake path or URI with `--flake <flake-uri>`.
|
||||
|
||||
After updating the lock file, rebuild with the command for your
|
||||
installation method.
|
||||
|
||||
For a standalone Home Manager flake:
|
||||
|
||||
``` shell
|
||||
$ home-manager switch --flake .
|
||||
```
|
||||
|
||||
For Home Manager as a NixOS module:
|
||||
|
||||
``` shell
|
||||
$ sudo nixos-rebuild switch --flake .
|
||||
```
|
||||
|
||||
For Home Manager as a nix-darwin module:
|
||||
|
||||
``` shell
|
||||
$ darwin-rebuild switch --flake .
|
||||
```
|
||||
|
||||
## Channel-Based Configurations {#sec-updating-channels}
|
||||
|
||||
Channels are mutable references outside the Home Manager configuration
|
||||
itself. Updating a channel moves it to a newer revision of the same
|
||||
channel or branch.
|
||||
|
||||
For a standalone Home Manager channel installation, update the user's
|
||||
channels and then switch:
|
||||
|
||||
``` shell
|
||||
$ nix-channel --update
|
||||
@@ -10,3 +66,19 @@ $ nix-channel --update
|
||||
unpacking channels...
|
||||
$ home-manager switch
|
||||
```
|
||||
|
||||
For Home Manager as a NixOS module, update the root user's Home Manager
|
||||
channel and rebuild the system:
|
||||
|
||||
``` shell
|
||||
$ sudo nix-channel --update home-manager
|
||||
$ sudo nixos-rebuild switch
|
||||
```
|
||||
|
||||
For Home Manager as a nix-darwin module, update the Home Manager channel
|
||||
used by your nix-darwin configuration and rebuild the system:
|
||||
|
||||
``` shell
|
||||
$ nix-channel --update home-manager
|
||||
$ darwin-rebuild switch
|
||||
```
|
||||
|
||||
@@ -2,66 +2,47 @@
|
||||
|
||||
## Overview {#sec-upgrade-release-overview}
|
||||
|
||||
When upgrading NixOS to a new major version (e.g., from 24.11 to
|
||||
25.05), you also need to upgrade your Home Manager channel to maintain
|
||||
compatibility. This guide covers the proper steps to upgrade Home
|
||||
Manager channels for NixOS 25.05.
|
||||
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 {#sec-upgrade-release-understanding-versioning}
|
||||
|
||||
Home Manager follows NixOS release cycles and provides corresponding branches:
|
||||
|
||||
- **release-##.##**: Stable branch for NixOS ##.## (current stable)
|
||||
- **release-<version>**: Stable branch for the matching NixOS or
|
||||
Nixpkgs release, such as `release-25.11`.
|
||||
|
||||
- **master**: Development branch (tracks nixos-unstable)
|
||||
|
||||
:::{.note}
|
||||
Always use the Home Manager version that matches your NixOS version to
|
||||
avoid compatibility issues.
|
||||
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.
|
||||
:::
|
||||
|
||||
## Channel-Based Installation (Traditional) {#sec-upgrade-release-understanding-channel}
|
||||
## Flake-Based Installation {#sec-upgrade-release-understanding-flake}
|
||||
|
||||
1. First, verify your current Home Manager channel:
|
||||
|
||||
``` shell
|
||||
$ nix-channel --list
|
||||
```
|
||||
|
||||
You should see something like:
|
||||
|
||||
```
|
||||
home-manager https://github.com/nix-community/home-manager/archive/release-24.11.tar.gz
|
||||
```
|
||||
|
||||
1. Update the Home Manager channel to a NixOS 25.05 compatible version:
|
||||
|
||||
``` shell
|
||||
$ nix-channel --add https://github.com/nix-community/home-manager/archive/release-25.05.tar.gz home-manager
|
||||
$ nix-channel --update
|
||||
```
|
||||
|
||||
1. Apply the changes:
|
||||
|
||||
``` shell
|
||||
$ home-manager switch
|
||||
```
|
||||
|
||||
## Flake-Based Installation (Modern) {#sec-upgrade-release-understanding-flake}
|
||||
|
||||
If you're using Home Manager with Nix flakes, update your `flake.nix`:
|
||||
If you are using Home Manager with Nix flakes, update your `nixpkgs` and
|
||||
`home-manager` inputs together:
|
||||
|
||||
```nix
|
||||
{
|
||||
description = "Home Manager configuration";
|
||||
|
||||
inputs = {
|
||||
# Increment release branch for NixOS
|
||||
nixpkgs.url = "github:NixOS/nixpkgs/nixos-25.05";
|
||||
# Match the Nixpkgs branch to the release you are using.
|
||||
nixpkgs.url = "github:NixOS/nixpkgs/nixos-25.11";
|
||||
|
||||
home-manager = {
|
||||
# Follow corresponding `release` branch from Home Manager
|
||||
url = "github:nix-community/home-manager/release-25.05";
|
||||
inputs.nixpkgs.follows = "nixpkgs";
|
||||
# Match the Home Manager branch to the Nixpkgs branch above.
|
||||
url = "github:nix-community/home-manager/release-25.11";
|
||||
};
|
||||
};
|
||||
|
||||
@@ -74,44 +55,115 @@ If you're using Home Manager with Nix flakes, update your `flake.nix`:
|
||||
}
|
||||
```
|
||||
|
||||
Then update and rebuild. If you are using Home Manager standalone:
|
||||
For `nixos-unstable` or `nixpkgs-unstable`, use the `master` branch
|
||||
instead:
|
||||
|
||||
```nix
|
||||
{
|
||||
inputs = {
|
||||
nixpkgs.url = "github:NixOS/nixpkgs/nixos-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:
|
||||
|
||||
``` shell
|
||||
$ nix flake update
|
||||
$ home-manager switch --flake .
|
||||
```
|
||||
|
||||
And if you are using Home Manager as a NixOS module then you will need
|
||||
to update your system configuration instead and run
|
||||
For Home Manager as a NixOS module:
|
||||
|
||||
``` shell
|
||||
$ nix flake update
|
||||
$ sudo nixos-rebuild switch --flake .
|
||||
```
|
||||
|
||||
For Home Manager as a nix-darwin module:
|
||||
|
||||
``` shell
|
||||
$ 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 {#sec-upgrade-release-understanding-channel}
|
||||
|
||||
For a standalone channel-based installation, first verify your current
|
||||
Home Manager channel:
|
||||
|
||||
``` shell
|
||||
$ 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:
|
||||
|
||||
``` shell
|
||||
$ 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:
|
||||
|
||||
``` shell
|
||||
$ 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:
|
||||
|
||||
``` shell
|
||||
$ 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 {#sec-upgrade-release-state-version}
|
||||
|
||||
:::{.warning}
|
||||
Careful updating your `home.stateVersion` when upgrading Home Manager.
|
||||
:::
|
||||
|
||||
The `stateVersion` is best to remain set to the NixOS version you
|
||||
**first installed** Home Manager
|
||||
The `stateVersion` should remain set to the Home Manager release you
|
||||
first used for this home configuration.
|
||||
|
||||
```nix
|
||||
{
|
||||
home.stateVersion = "24.11"; # Example: if you first installed on 24.11
|
||||
# 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 version is not the same as State version. Update
|
||||
the channel, keep the `stateVersion` unchanged. Advanced users can
|
||||
view the changes between releases and see if any of the `stateVersion`
|
||||
changes will affect them and increment, if they migrate their
|
||||
configurations to follow the changed evaluation.
|
||||
**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 {#sec-upgrade-release-state-troubleshooting}
|
||||
|
||||
@@ -120,8 +172,9 @@ configurations to follow the changed evaluation.
|
||||
Check the [Home Manager Release Notes](#ch-release-notes) for breaking changes.
|
||||
|
||||
1. **Version Mismatch Warning**: If you see warnings about version
|
||||
mismatches, ensure your Home Manager version matches your NixOS
|
||||
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.
|
||||
|
||||
1. **Module Changes**: Modules are constantly being updated with new
|
||||
features to keep up with changes in upstream packaging or to fix
|
||||
@@ -129,8 +182,8 @@ Check the [Home Manager Release Notes](#ch-release-notes) for breaking changes.
|
||||
there was something noted in the release notes or news entries.
|
||||
|
||||
1. **Channel Not Found**: If `nix-channel --list` shows no channels,
|
||||
you might be using a different installation method (like flakes or
|
||||
NixOS module).
|
||||
you might be using a different installation method, such as flakes,
|
||||
or Home Manager may be imported through your system configuration.
|
||||
|
||||
### Verification {#sec-upgrade-release-state-troubleshooting-verification}
|
||||
|
||||
@@ -140,7 +193,8 @@ After upgrading, verify the installation:
|
||||
$ home-manager --version
|
||||
```
|
||||
|
||||
This should show version 25.05 or indicate it's using the release-25.05 branch.
|
||||
This should show the Home Manager version or indicate that it is using
|
||||
the expected release branch.
|
||||
|
||||
## Additional Resources {#sec-upgrade-release-resources}
|
||||
|
||||
|
||||
Reference in New Issue
Block a user