depot/third_party/home-manager/docs/release-notes/rl-2211.md

Release 22.11

The 22.11 release branch became the stable branch in November, 2022.

Highlights

This release has the following notable changes:

• The home.stateVersion option no longer has a default value. It used to default to "18.09", which was the Home Manager version that introduced the option. If your configuration does not explicitly set this option then you need to add

  home.stateVersion = "18.09";
  

  to your configuration.

• The Flake function homeManagerConfiguration has been simplified. Specifically, the arguments

  • configuration,

  • username,

  • homeDirectory,

  • stateVersion,

  • extraModules, and

  • system

  have been removed. Instead use the new modules argument, which accepts a list of NixOS modules.

  Further, the pkgs argument is now mandatory and should be set to nixpkgs.legacyPackages.${system} where nixpkgs is the Nixpkgs input of your choice.

  For example, if your Flake currently contains

  homeManagerConfiguration {
    configuration = import ./home.nix;
    system = "x86_64-linux";
    username = "jdoe";
    homeDirectory = "/home/jdoe";
    stateVersion = "22.05";
    extraModules = [ ./some-extra-module.nix ];
  }
  

  then you can change it to

  homeManagerConfiguration {
    pkgs = nixpkgs.legacyPackages.${system};
    modules = [
      ./home.nix
      ./some-extra-module.nix
      {
        home = {
          username = "jdoe";
          homeDirectory = "/home/jdoe";
          stateVersion = "22.05";
        };
      }
    ];
  }
  

  Of course, you can move the assignment of home.username, home.stateVersion to some other file or simply place them in your home.nix.

• The services.picom module has been refactored to use structural settings.

  As a result services.picom.extraOptions has been removed in favor of services.picom.settings. Also, services.picom.blur* were removed since upstream changed the blur settings to be more flexible. You can migrate the blur settings to use services.picom.settings instead.

• The services.compton module has been removed. It was deprecated in release 20.03. Use services.picom instead.

State Version Changes

The state version in this release includes the changes below. These changes are only active if the home.stateVersion option is set to "22.11" or later.

• The services.mpd.musicDirectory option now defaults to the value of xdg.userDirs.music if xdg.userDirs.enable is enabled. Otherwise it is undefined and must be specified in the user configuration.

• The activation script now resets PATH before running. Before, the user's PATH environment variable would be used in the script and this made it possible for commands in the activation script to run arbitrary commands accessible to the user. We now restrict the activation script to commands that are explicitly specified.

  There is no official way to restore the old behavior. We attempt to make the activation script as reproducible as possible and honoring the user's PATH reduces reproducibility.

  If you need to run a command in an activation script block then refer to the command by its absolute command path, such as ${pkgs.hello}/bin/hello.