Release Notes

C.1. Release 20.09 (unreleased)
C.1.1. Highlights
C.1.2. State Version Changes
C.2. Release 20.03
C.2.1. Highlights
C.2.2. State Version Changes
C.3. Release 19.09
C.3.1. Highlights
C.3.2. State Version Changes
C.4. Release 19.03
C.4.1. Highlights
C.4.2. State Version Changes
C.5. Release 18.09

This section lists the release notes for stable versions of Home Manager and the current unstable version.

C.1. Release 20.09 (unreleased)

This is the current unstable branch and the information in this section is therefore not final.

C.1.1. Highlights

This release has the following notable changes:

  • Nothing has happened.

C.1.2. 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 "20.09" or later.

  • The options home.homeDirectory and home.username no longer have default values and must therefore be provided in your configuration. Previously their values would default to the content of the environment variables HOME and USER, respectively.

    Further, the options xdg.cacheHome, xdg.configHome, and xdg.dataHome will no longer be affected by the XDG_CACHE_HOME, XDG_CONFIG_HOME, and XDG_DATA_HOME environment variables. They now unconditionally default to

    • "${config.home.homeDirectory}/.cache",
    • "${config.home.homeDirectory}/.config", and
    • "${config.home.homeDirectory}/.local/share".

    If you choose to switch to state version 20.09 then you must set these options if you use non-default XDG base directory paths.

    The initial configuration generated by

    $ nix-shell '<home-manager>' -A install

    will automatically include these options, when necessary.

C.2. Release 20.03

The 20.03 release branch became the stable branch in April, 2020.

C.2.1. Highlights

This release has the following notable changes:

  • Assigning a list to the home.file, xdg.configFile, and xdg.dataFile options is now deprecated and will produce a warning message if used. Specifically, if your configuration currently contains something like

    home.file = [
      {
        target = ".config/foo.txt";
        text = "bar";
      }
    ]

    then it should be updated to instead use the equivalent attribute set form

    home.file = {
      ".config/foo.txt".text = "bar";
    }

    Support for the list form will be removed in Home Manager version 20.09.

  • The lib function attribute given to modules is now enriched with an attribute hm containing extra library functions specific for Home Manager. More specifically, lib.hm is now the same as config.lib and should be the preferred choice since it is more robust.

    Therefore, if your configuration makes use of, for example, config.lib.dag to create activation script blocks, it is recommended to change to lib.hm.dag.

    Note, in the unlikely case that you are

    • using Home Manager’s NixOS or nix-darwin module,
    • have made your own Home Manager module containing an top-level option named config or options, and
    • assign to this option in your system configuration inside a plain attribute set, i.e., without a function argument,

    then you must update your configuration to perform the option assignment inside a config attribute. For example, instead of

    home-manager.users.jane = { config = "foo"; };

    use

    home-manager.users.jane = { config.config = "foo"; };
  • The services.compton module has been deprecated and instead the new module services.picom should be used. This is because Nixpkgs no longer packages compton, and instead packages the (mostly) compatible fork called picom.
  • The list form of the programs.ssh.matchBlocks option has been deprecated and configurations requiring match blocks in a defined order should switch to using DAG entries instead. For example, a configuration

    programs.ssh.matchBlocks = [
      {
        host = "alpha.foo.com";
        user = "jd";
      }
      {
        host = "*.foo.com";
        user = "john.doe";
      }
    ];

    can be expressed along the lines of

    programs.ssh.matchBlocks = {
      "*.example.com" = {
        user = "john.doe";
      }
      "alpha.example.com" = lib.hm.dag.entryBefore ["*.example.com"] {
        user = "jd";
      }
    };

    Support for the list form will be removed in Home Manager version 20.09.

C.2.2. 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 "20.03" or later.

  • The programs.zsh.history.path option is no longer prepended by $HOME, which allows specifying absolute paths, for example, using the xdg module. Also, the default value is fixed to $HOME/.zsh_history and dotDir path is not prepended to it anymore.
  • The newsboat module will now default in displaying queries before urls in its main window. This makes sense in the case when one has a lot of URLs and few queries.

C.3. Release 19.09

The 19.09 release branch became the stable branch in October, 2019.

C.3.1. Highlights

This release has the following notable changes:

  • The programs.firefox.enableGoogleTalk and programs.firefox.enableIcedTea options are now deprecated and will only work if Firefox ESR 52.x is used.
  • The home-manager tool now provides an uninstall sub-command that can be used to uninstall Home Manager, if used in the standalone mode. That is, not as a NixOS module.

C.3.2. 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 "19.09" or later.

C.4. Release 19.03

The 19.03 release branch became the stable branch in April, 2019.

C.4.1. Highlights

This release has the following notable changes:

  • The home.file.<name?>.source option now allows source files to be hidden, that is, having a name starting with the . character. It also allows the source file name to contain characters not typically allowed for Nix store paths. For example, your configuration can now contain things such as

    home.file."my file".source = ./. + "/file with spaces!";
  • The type used for the systemd unit options under systemd.user.services, systemd.user.sockets, etc. has been changed to offer more robust merging of configurations. If you don’t override values within systemd units then you are not affected by this change. Unfortunately, if you do override unit values you may encounter errors.

    In particular, if you get an error saying that a “unique option” is “defined multiple times” then you need to use the mkForce function. For example,

    systemd.user.services.foo.Service.ExecStart = "/foo/bar";

    becomes

    systemd.user.services.foo.Service.ExecStart = lib.mkForce "/foo/bar";

    We had to make this change because the old merging was causing too many confusing situations for people.

C.4.2. 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 “19.03” or later.

C.5. Release 18.09

The 18.09 release branch became the stable branch in September, 2018.