Appendix D. Release Notes

Table of Contents

Release 24.05
Release 23.11
Release 23.05
Release 22.11
Release 22.05
Release 21.11
Release 21.05
Release 20.09
Release 20.03
Release 19.09
Release 19.03
Release 18.09

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

Release 24.05

Table of Contents

Highlights
State Version Changes

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

Highlights

This release has the following notable changes:

  • The .release file in the Home Manager project root has been removed. Please use the release.json file 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 "24.05" or later.

  • Nothing, yet.

Release 23.11

Table of Contents

Highlights
State Version Changes

The 23.11 release branch became stable in November, 2023.

Highlights

This release has the following notable changes:

  • When using opt-programs.fish.enable, the setup code for opt-home.sessionVariables is now translated with babelfish. This should result in significantly faster shell startup times but could theoretically break if you have very complex bash expressions in a session variable. Please report any issues you experience.

  • The .release file in the Home Manager source tree has been supplanted by release.json, which contains more information about the branch. If you have any external code reading this file, please switch to consuming release.json instead. The .release file will be removed in 24.05.

  • Home Manager has migrated to using the upstream Nixpkgs lib.nixosOptionsDoc processor for option documentation. If you have any external Home Manager modules, their option descriptions and literal examples should be translated to Nixpkgs-flavoured Markdown.

  • The services.password-store-sync module has been removed. Use services.git-sync 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 "23.11" or later.

  • Nothing, yet.

Release 23.05

Table of Contents

Highlights
State Version Changes

The 23.05 release branch became the stable branch in May, 2023.

Highlights

This release has the following notable changes:

  • Firefox add-ons are now managed per-profile. That is, if you are currently having

    programs.firefox.extensions = [ foo bar ];
    

    in your configuration then you must change it to

    programs.firefox.profiles.myprofile.extensions = [ foo bar ];
    
  • The default configuration location has been changed from ~/.config/nixpkgs/home.nix to ~/.config/home-manager/home.nix.

    Similarly, if you are using a Nix flake based setup then the default flake file location has changed from ~/.config/nixpkgs/flake.nix to ~/.config/home-manager/flake.nix.

    The old location will continue to work but using it will trigger a warning message. We changed the default configuration location to avoid confusion about which files belong to Home Manager and which belong to Nixpkgs.

  • The home-manager tool now offers an init command. This command can be used to generate an initial Home Manager configuration, and optionally also activate it. The recommended installation method for a standalone Home Manager setup with Nix flakes uses this new command. The standard installation method remains the same but uses the new command internally. See sec-flakes-standalone for more.

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 "23.05" or later.

Release 22.11

Table of Contents

Highlights
State Version Changes

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

Highlights

This release has the following notable changes:

  • The opt-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 opt-home.username, opt-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 opt-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 opt-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 opt-services.mpd.musicDirectory option now defaults to the value of opt-xdg.userDirs.music if opt-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.

Release 22.05

Table of Contents

Highlights
State Version Changes

The 22.05 release branch became the stable branch in May, 2022.

Highlights

This release has the following notable changes:

  • The programs.waybar.settings.modules option was removed. Waybar modules should now be declared directly under programs.waybar.settings.

  • Home Manager now partially support translation of texts into different languages. Note, the support is quite limited at the moment. Specifically, it only applies to parts of the system written in the Bash language, such as the home-manager command line tool and the activation script.

    If you would like to contribute to the translation effort then you can do so through the Home Manager Weblate project.

  • A new module, launchd.agents was added. Use this to enable services based on macOS LaunchAgents.

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.05" or later.

  • The opt-programs.waybar.settings option now allows defining modules directly under opt-programs.waybar.settings. Defining modules under programs.waybar.settings.modules will now be an error. For example,

    programs.waybar.settings.modules."custom/my-module" = { };
    

    becomes

    programs.waybar.settings."custom/my-module" = { };
    

Release 21.11

Table of Contents

Highlights
State Version Changes

The 21.11 release branch became the stable branch in November, 2021.

Highlights

This release has the following notable changes:

  • All Home Manager modules are now loaded on all platforms. With this change you will get a more descriptive error message if you attempt to enable a module that is incompatible with the host platform.

    Previously, modules that were platform specific would only be loaded on that particular platform. For example, a module defining a systemd service would only be loaded when the host platform was Linux. This reduced evaluation times, simplified the generated documentation, and made it impossible to accidentally use modules that do not support the host platform.

    While the above benefits are quite nice, avoiding module loads also brings a few problems. For example, the public documentation will only show the options available for Linux hosts and the documentation cannot make references to options within modules that are unavailable on some hosts. Finally, users who wish to use the same configuration file for different platforms cannot do so, even if the platform incompatible options are unused.

    Ultimately, the benefits of loading all modules won and the behavior has now changed. For associated discussion see issue #1906.

  • Rofi version 1.7.0 removed many options that were used by the module and replaced them with custom themes, which are more flexible and powerful.

    You can replicate your old configuration by moving those options to opt-programs.rofi.theme. Keep in mind that the syntax is different so you may need to do some changes.

  • Taskwarrior version 2.6.0 respects XDG Specification for the config file now. Option opt-programs.taskwarrior.config and friends now generate the config file at $XDG_CONFIG_HOME/task/taskrc instead of ~/.taskrc.

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 "21.11" or later.

  • The opt-home.keyboard option now defaults to null, meaning that Home Manager won’t do any keyboard layout management. For example, setxkbmap won’t be run in X sessions.

  • The opt-programs.pet.settings option no longer place its value inside a General attribute. For example,

    programs.pet.settings.editor = "nvim";
    

    becomes

    programs.pet.settings.General.editor = "nvim";
    
  • The opt-programs.waybar.settings option now allows defining modules directly under opt-programs.waybar.settings. For example,

    programs.waybar.settings.modules."custom/my-module" = { };
    

    becomes

    programs.waybar.settings."custom/my-module" = { };
    

Release 21.05

Table of Contents

Highlights
State Version Changes

The 21.05 release branch became the stable branch in May, 2021.

Highlights

This release has the following notable changes:

  • The ‘opt-programs.broot.verbs` option is now a list rather than an attribute set. To migrate, move the keys of the attrset into the list items’ invocation keys. For example,

    programs.broot.verbs = {
      "p" = { execution = ":parent"; };
    };
    

    becomes

    programs.broot.verbs = [
      {
        invocation = "p";
        execution = ":parent";
      }
    ];
    
  • The opt-programs.mpv.package option has been changed to allow custom derivations. The following configuration is now possible:

    programs.mpv.package = (pkgs.wrapMpv (pkgs.mpv-unwrapped.override {
      vapoursynthSupport = true;
    }) {
      extraMakeWrapperArgs = [
        "--prefix" "LD_LIBRARY_PATH" ":" "${pkgs.vapoursynth-mvtools}/lib/vapoursynth"
      ];
    });
    

    As a result of this change, opt-programs.mpv.package is no longer the resulting derivation. Use the newly introduced programs.mpv.finalPackage instead.

  • The opt-programs.rofi.extraConfig option is now an attribute set rather than a string. To migrate, move each line into the attribute set, removing the rofi. prefix from the keys. For example,

    programs.rofi.extraConfig = ''
      rofi.show-icons: true
      rofi.modi: drun,emoji,ssh
    '';
    

    becomes

    programs.rofi.extraConfig = {
      show-icons = true;
      modi = "drun,emoji,ssh";
    };
    
  • The opt-programs.rofi.theme option now supports defining a theme using an attribute set, the following configuration is now possible:

    programs.rofi.theme = let
      # Necessary to avoid quoting non-string values
      inherit (config.lib.formats.rasi) mkLiteral;
    in {
       "@import" = "~/.config/rofi/theme.rasi";
    
      "*" = {
        background-color = mkLiteral "#000000";
        foreground-color = mkLiteral "rgba ( 250, 251, 252, 100 % )";
        border-color = mkLiteral "#FFFFFF";
        width = 512;
      };
    
      "#textbox-prompt-colon" = {
        expand = false;
        str = ":";
        margin = mkLiteral "0px 0.3em 0em 0em";
        text-color = mkLiteral "@foreground-color";
      };
    };
    
  • The services.redshift.extraOptions and services.gammastep.extraOptions options were removed in favor of opt-services.redshift.settings and services.gammastep.settings, that are now an attribute set rather than a string. They also support new features not available before, for example:

    services.redshift = {
      dawnTime = "6:00-7:45";
      duskTime = "18:35-20:15";
      settings = {
        redshift = {
          gamma = 0.8;
          adjustment-method = "randr";
        };
    
        randr = {
          screen = 0;
        };
      };
    };
    

    It is recommended to check either redshift.conf.sample or gammastep.conf.sample for the available additional options in each program.

  • Specifying programs.neomutt.binds.map or programs.neomutt.macros.map as a single string is now deprecated in favor of specfiying it as a list of strings.

  • The programs.neovim.configure is deprecated in favor of other programs.neovim options; please use the other options at your disposal:

    configure.packages.*.opt  -> programs.neovim.plugins = [ { plugin = ...; optional = true; }]
    configure.packages.*.start  -> programs.neovim.plugins = [ { plugin = ...; }]
    configure.customRC -> programs.neovim.extraConfig
    
  • Home Manager now respects the NO_COLOR environment variable as per https://no-color.org/.

  • Qt module now supports opt-qt.style.name to specify a theme name and opt-qt.style.package to specify a theme package. If you have set opt-qt.platformTheme to gnome, a opt-qt.style.package compatible with both Qt and Gtk is now required to be set. For instance:

    qt = {
      platformTheme = "gnome";
      style = {
        name = "adwaita-dark";
        package = pkgs.adwaita-qt;
      };
    };
    
  • The library type fontType now has a size attribute in addition to name. For example:

    font = {
      name = "DejaVu Sans";
      size = 8;
    };
    
  • The opt-programs.htop.settings option is introduced to replace individual options in programs.htop. To migrate, set the htop options directly in opt-programs.htop.settings. For example:

    programs.htop = {
      enabled = true;
      settings = {
         color_scheme = 5;
         delay = 15;
         highlight_base_name = 1;
         highlight_megabytes = 1;
         highlight_threads = 1;
      };
    };
    

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 "21.05" or later.

  • The newsboat module now stores generated configuration in $XDG_CONFIG_HOME/newsboat.

Release 20.09

Table of Contents

Highlights
State Version Changes

The 20.09 release branch became the stable branch in late September, 2020.

Highlights

This release has the following notable changes:

  • Nothing has happened.

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 opt-home.homeDirectory and opt-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 opt-xdg.cacheHome, opt-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.

  • Git’s smtpEncryption option is now set to tls only if both opt-accounts.email.accounts.name.smtp.tls.enable and opt-accounts.email.accounts.name.smtp.tls.useStartTls are true. If only opt-accounts.email.accounts.name.smtp.tls.enable is true, ssl is used instead.

  • The nixpkgs module no longer references <nixpkgs>. Before it would do so when building the pkgs module argument. Starting with state version 20.09, the pkgs argument is instead built from the same Nixpkgs that was used to initialize the Home Manager modules. This is useful, for example, when using Home Manager within a Nix Flake. If you want to keep using <nixpkgs> with state version ≥ 20.09 then add

    _module.args.pkgsPath = <nixpkgs>;
    

    to your Home Manager configuration.

  • The options wayland.windowManager.sway.config.bars and opt-xsession.windowManager.i3.config.bars have been changed so that most of the suboptions are now nullable and default to null. The default for these two options has been changed to manually set the old defaults for each suboption. The overall effect is that if the bars options is not set, then the default remains the same. On the other hand, something like:

    bars = [ {
      command = "waybar";
    } ];
    

    will now create the config:

    bar {
      swaybar_command waybar
    }
    

    instead of

    bar {
    
      font pango:monospace 8
      mode dock
      hidden_state hide
      position bottom
      status_command /nix/store/h7s6i9q1z5fxrlyyw5ls8vqxhf5bcs5a-i3status-2.13/bin/i3status
      swaybar_command waybar
      workspace_buttons yes
      strip_workspace_numbers no
      tray_output primary
      colors {
        background #000000
        statusline #ffffff
        separator #666666
        focused_workspace #4c7899 #285577 #ffffff
        active_workspace #333333 #5f676a #ffffff
        inactive_workspace #333333 #222222 #888888
        urgent_workspace #2f343a #900000 #ffffff
        binding_mode #2f343a #900000 #ffffff
      }
    
    }
    

Release 20.03

Table of Contents

Highlights
State Version Changes

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

Highlights

This release has the following notable changes:

  • Assigning a list to the opt-home.file, opt-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 opt-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.

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

Release 19.09

Table of Contents

Highlights
State Version Changes

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

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.

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.

Release 19.03

Table of Contents

Highlights
State Version Changes

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

Highlights

This release has the following notable changes:

  • The opt-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 opt-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.

State Version Changes

The state version in this release includes the changes below. These changes are only active if the opt-home.stateVersion option is set to “19.03” or later.

Release 18.09

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