<?xml version="1.0" encoding="UTF-8" standalone="no"?> <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Appendix E. Release Notes</title><link rel="stylesheet" type="text/css" href="style.css" /><link rel="stylesheet" type="text/css" href="overrides.css" /><link rel="stylesheet" type="text/css" href="mono-blue.css" /><script src="highlight.pack.js" type="text/javascript"></script><script src="highlight.load.js" type="text/javascript"></script><meta name="generator" content="DocBook XSL Stylesheets V1.79.2" /><link rel="home" href="index.html" title="Home Manager Manual" /><link rel="up" href="index.html" title="Home Manager Manual" /><link rel="prev" href="tools.html" title="Appendix D. Tools" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Appendix E. Release Notes</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="tools.html">Prev</a> </td><th width="60%" align="center"> </th><td width="20%" align="right"> </td></tr></table><hr /></div><div class="appendix"><div class="titlepage"><div><div><h1 class="title"><a id="ch-release-notes"></a>Release Notes</h1></div></div></div><div class="toc"><dl class="toc"><dt><span class="section"><a href="release-notes.html#sec-release-21.05">E.1. Release 21.05</a></span></dt><dd><dl><dt><span class="section"><a href="release-notes.html#sec-release-21.05-highlights">E.1.1. Highlights</a></span></dt><dt><span class="section"><a href="release-notes.html#sec-release-21.05-state-version-changes">E.1.2. State Version Changes</a></span></dt></dl></dd><dt><span class="section"><a href="release-notes.html#sec-release-20.09">E.2. Release 20.09</a></span></dt><dd><dl><dt><span class="section"><a href="release-notes.html#sec-release-20.09-highlights">E.2.1. Highlights</a></span></dt><dt><span class="section"><a href="release-notes.html#sec-release-20.09-state-version-changes">E.2.2. State Version Changes</a></span></dt></dl></dd><dt><span class="section"><a href="release-notes.html#sec-release-20.03">E.3. Release 20.03</a></span></dt><dd><dl><dt><span class="section"><a href="release-notes.html#sec-release-20.03-highlights">E.3.1. Highlights</a></span></dt><dt><span class="section"><a href="release-notes.html#sec-release-20.03-state-version-changes">E.3.2. State Version Changes</a></span></dt></dl></dd><dt><span class="section"><a href="release-notes.html#sec-release-19.09">E.4. Release 19.09</a></span></dt><dd><dl><dt><span class="section"><a href="release-notes.html#sec-release-19.09-highlights">E.4.1. Highlights</a></span></dt><dt><span class="section"><a href="release-notes.html#sec-release-19.09-state-version-changes">E.4.2. State Version Changes</a></span></dt></dl></dd><dt><span class="section"><a href="release-notes.html#sec-release-19.03">E.5. Release 19.03</a></span></dt><dd><dl><dt><span class="section"><a href="release-notes.html#sec-release-19.03-highlights">E.5.1. Highlights</a></span></dt><dt><span class="section"><a href="release-notes.html#sec-release-19.03-state-version-changes">E.5.2. State Version Changes</a></span></dt></dl></dd><dt><span class="section"><a href="release-notes.html#sec-release-18.09">E.6. Release 18.09</a></span></dt></dl></div><p>This section lists the release notes for stable versions of Home Manager and the current unstable version.</p><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="sec-release-21.05"></a>E.1. Release 21.05</h2></div></div></div><p>This is the current unstable branch and the information in this section is therefore not final.</p><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="sec-release-21.05-highlights"></a>E.1.1. Highlights</h3></div></div></div><p>This release has the following notable changes:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p class="simpara"> The <a class="xref" href="options.html#opt-programs.broot.verbs"><code class="option">programs.broot.verbs</code></a> option is now a list rather than an attribute set. To migrate, move the keys of the attrset into the list items' <code class="literal">invocation</code> keys. For example, </p><pre class="programlisting nix">programs.broot.verbs = { "p" = { execution = ":parent"; }; };</pre><p class="simpara">becomes</p><pre class="programlisting nix">programs.broot.verbs = [ { invocation = "p"; execution = ":parent"; } ];</pre></li><li class="listitem"><p class="simpara"> The <a class="xref" href="options.html#opt-programs.mpv.package"><code class="option">programs.mpv.package</code></a> option has been changed to allow custom derivations. The following configuration is now possible: </p><pre class="programlisting nix">programs.mpv.package = (pkgs.wrapMpv (pkgs.mpv-unwrapped.override { vapoursynthSupport = true; }) { extraMakeWrapperArgs = [ "--prefix" "LD_LIBRARY_PATH" ":" "${pkgs.vapoursynth-mvtools}/lib/vapoursynth" ]; });</pre><p class="simpara">As a result of this change, <a class="xref" href="options.html#opt-programs.mpv.package"><code class="option">programs.mpv.package</code></a> is no longer the resulting derivation. Use the newly introduced <code class="literal">programs.mpv.finalPackage</code> instead.</p></li><li class="listitem"><p class="simpara"> The <a class="xref" href="options.html#opt-programs.rofi.extraConfig"><code class="option">programs.rofi.extraConfig</code></a> option is now an attrset rather than a string. To migrate, move the each line into the attrset, removing the <code class="literal">rofi.</code> prefix from the keys. For example, </p><pre class="programlisting nix">programs.rofi.extraConfig = '' rofi.show-icons: true rofi.modi: drun,emoji,ssh '';</pre><p class="simpara">becomes</p><pre class="programlisting nix">programs.rofi.extraConfig = { show-icons = true; modi = "drun,emoji,ssh"; };</pre></li><li class="listitem"><p class="simpara"> The <code class="literal">services.redshift.extraOptions</code> and <code class="literal">services.gammastep.extraOptions</code> options were removed in favor of <a class="xref" href="options.html#opt-services.redshift.settings"><code class="option">services.redshift.settings</code></a> and <code class="literal">services.gammastep.settings</code>, that are now an attribute set rather than a string. They also support new features not available before, for example: </p><pre class="programlisting nix">services.redshift = { dawnTime = "6:00-7:45"; duskTime = "18:35-20:15"; settings = { redshift = { gamma = 0.8; adjustment-method = "randr"; }; randr = { screen = 0; }; }; };</pre><p class="simpara">It is recommended to check either <a class="link" href="https://github.com/jonls/redshift/blob/master/redshift.conf.sample" target="_top">redshift.conf.sample</a> or <a class="link" href="https://gitlab.com/chinstrap/gammastep/-/blob/master/gammastep.conf.sample" target="_top">gammastep.conf.sample</a> for the available additional options in each program.</p></li></ul></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="sec-release-21.05-state-version-changes"></a>E.1.2. State Version Changes</h3></div></div></div><p>The state version in this release includes the changes below. These changes are only active if the <code class="literal">home.stateVersion</code> option is set to "21.05" or later.</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"> Nothing has happened. </li></ul></div></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="sec-release-20.09"></a>E.2. Release 20.09</h2></div></div></div><p>The 20.09 release branch became the stable branch in late September, 2020.</p><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="sec-release-20.09-highlights"></a>E.2.1. Highlights</h3></div></div></div><p>This release has the following notable changes:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"> Nothing has happened. </li></ul></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="sec-release-20.09-state-version-changes"></a>E.2.2. State Version Changes</h3></div></div></div><p>The state version in this release includes the changes below. These changes are only active if the <code class="literal">home.stateVersion</code> option is set to "20.09" or later.</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p class="simpara"> The options <a class="xref" href="options.html#opt-home.homeDirectory"><code class="option">home.homeDirectory</code></a> and <a class="xref" href="options.html#opt-home.username"><code class="option">home.username</code></a> 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 <code class="literal">HOME</code> and <code class="literal">USER</code>, respectively. </p><p class="simpara">Further, the options <a class="xref" href="options.html#opt-xdg.cacheHome"><code class="option">xdg.cacheHome</code></a>, <a class="xref" href="options.html#opt-xdg.configHome"><code class="option">xdg.configHome</code></a>, and <a class="xref" href="options.html#opt-xdg.dataHome"><code class="option">xdg.dataHome</code></a> will no longer be affected by the <code class="literal">XDG_CACHE_HOME</code>, <code class="literal">XDG_CONFIG_HOME</code>, and <code class="literal">XDG_DATA_HOME</code> environment variables. They now unconditionally default to</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"> <code class="literal">"${config.home.homeDirectory}/.cache"</code>, </li><li class="listitem"> <code class="literal">"${config.home.homeDirectory}/.config"</code>, and </li><li class="listitem"> <code class="literal">"${config.home.homeDirectory}/.local/share"</code>. </li></ul></div><p class="simpara">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.</p><p class="simpara">The initial configuration generated by</p><pre class="programlisting console">$ nix-shell '<home-manager>' -A install</pre><p class="simpara">will automatically include these options, when necessary.</p></li><li class="listitem"> Git’s <code class="literal">smtpEncryption</code> option is now set to <code class="literal">tls</code> only if both <a class="xref" href="options.html#opt-accounts.email.accounts._name_.smtp.tls.enable"><code class="option">accounts.email.accounts.<name>.smtp.tls.enable</code></a> and <a class="xref" href="options.html#opt-accounts.email.accounts._name_.smtp.tls.useStartTls"><code class="option">accounts.email.accounts.<name>.smtp.tls.useStartTls</code></a> are <code class="literal">true</code>. If only <a class="xref" href="options.html#opt-accounts.email.accounts._name_.smtp.tls.enable"><code class="option">accounts.email.accounts.<name>.smtp.tls.enable</code></a> is <code class="literal">true</code>, <code class="literal">ssl</code> is used instead. </li><li class="listitem"><p class="simpara"> The <code class="literal">nixpkgs</code> module no longer references <code class="literal"><nixpkgs></code>. Before it would do so when building the <code class="literal">pkgs</code> module argument. Starting with state version 20.09, the <code class="literal">pkgs</code> 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 <code class="literal"><nixpkgs></code> with state version ≥ 20.09 then add </p><pre class="programlisting nix">_module.args.pkgsPath = <nixpkgs>;</pre><p class="simpara">to your Home Manager configuration.</p></li><li class="listitem"><p class="simpara"> The options <code class="literal">wayland.windowManager.sway.config.bars</code> and <code class="literal">opt-xsession.windowManager.i3.config.bars</code> have been changed so that most of the suboptions are now nullable and default to <code class="literal">null</code>. 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 <code class="literal">bars</code> options is not set, then the default remains the same. On the other hand, something like: </p><pre class="programlisting nix">bars = [ { command = "waybar"; } ];</pre><p class="simpara">will now create the config:</p><pre class="literallayout">bar { swaybar_command waybar }</pre><p class="simpara">instead of</p><pre class="literallayout">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 } }</pre></li></ul></div></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="sec-release-20.03"></a>E.3. Release 20.03</h2></div></div></div><p>The 20.03 release branch became the stable branch in April, 2020.</p><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="sec-release-20.03-highlights"></a>E.3.1. Highlights</h3></div></div></div><p>This release has the following notable changes:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p class="simpara"> Assigning a list to the <a class="xref" href="options.html#opt-home.file"><code class="option">home.file</code></a>, <a class="xref" href="options.html#opt-xdg.configFile"><code class="option">xdg.configFile</code></a>, and <a class="xref" href="options.html#opt-xdg.dataFile"><code class="option">xdg.dataFile</code></a> options is now deprecated and will produce a warning message if used. Specifically, if your configuration currently contains something like </p><pre class="programlisting nix">home.file = [ { target = ".config/foo.txt"; text = "bar"; } ]</pre><p class="simpara">then it should be updated to instead use the equivalent attribute set form</p><pre class="programlisting nix">home.file = { ".config/foo.txt".text = "bar"; }</pre><p class="simpara">Support for the list form will be removed in Home Manager version 20.09.</p></li><li class="listitem"><p class="simpara"> The <code class="literal">lib</code> function attribute given to modules is now enriched with an attribute <code class="literal">hm</code> containing extra library functions specific for Home Manager. More specifically, <code class="literal">lib.hm</code> is now the same as <code class="literal">config.lib</code> and should be the preferred choice since it is more robust. </p><p class="simpara">Therefore, if your configuration makes use of, for example, <code class="literal">config.lib.dag</code> to create activation script blocks, it is recommended to change to <code class="literal">lib.hm.dag</code>.</p><p class="simpara">Note, in the unlikely case that you are</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"> using Home Manager’s NixOS or nix-darwin module, </li><li class="listitem"> have made your own Home Manager module containing an top-level option named <code class="literal">config</code> or <code class="literal">options</code>, and </li><li class="listitem"> assign to this option in your system configuration inside a plain attribute set, i.e., without a function argument, </li></ul></div><p class="simpara">then you must update your configuration to perform the option assignment inside a <code class="literal">config</code> attribute. For example, instead of</p><pre class="programlisting nix">home-manager.users.jane = { config = "foo"; };</pre><p class="simpara">use</p><pre class="programlisting nix">home-manager.users.jane = { config.config = "foo"; };</pre></li><li class="listitem"> The <code class="literal">services.compton</code> module has been deprecated and instead the new module <code class="literal">services.picom</code> should be used. This is because Nixpkgs no longer packages compton, and instead packages the (mostly) compatible fork called picom. </li><li class="listitem"><p class="simpara"> The list form of the <a class="xref" href="options.html#opt-programs.ssh.matchBlocks"><code class="option">programs.ssh.matchBlocks</code></a> option has been deprecated and configurations requiring match blocks in a defined order should switch to using DAG entries instead. For example, a configuration </p><pre class="programlisting nix">programs.ssh.matchBlocks = [ { host = "alpha.foo.com"; user = "jd"; } { host = "*.foo.com"; user = "john.doe"; } ];</pre><p class="simpara">can be expressed along the lines of</p><pre class="programlisting nix">programs.ssh.matchBlocks = { "*.example.com" = { user = "john.doe"; } "alpha.example.com" = lib.hm.dag.entryBefore ["*.example.com"] { user = "jd"; } };</pre><p class="simpara">Support for the list form will be removed in Home Manager version 20.09.</p></li></ul></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="sec-release-20.03-state-version-changes"></a>E.3.2. State Version Changes</h3></div></div></div><p>The state version in this release includes the changes below. These changes are only active if the <code class="literal">home.stateVersion</code> option is set to "20.03" or later.</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"> The <a class="xref" href="options.html#opt-programs.zsh.history.path"><code class="option">programs.zsh.history.path</code></a> option is no longer prepended by <code class="literal">$HOME</code>, which allows specifying absolute paths, for example, using the xdg module. Also, the default value is fixed to <code class="literal">$HOME/.zsh_history</code> and <code class="literal">dotDir</code> path is not prepended to it anymore. </li><li class="listitem"> The newsboat module will now default in displaying <code class="literal">queries</code> before <code class="literal">urls</code> in its main window. This makes sense in the case when one has a lot of URLs and few queries. </li></ul></div></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="sec-release-19.09"></a>E.4. Release 19.09</h2></div></div></div><p>The 19.09 release branch became the stable branch in October, 2019.</p><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="sec-release-19.09-highlights"></a>E.4.1. Highlights</h3></div></div></div><p>This release has the following notable changes:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"> The <code class="literal">programs.firefox.enableGoogleTalk</code> and <code class="literal">programs.firefox.enableIcedTea</code> options are now deprecated and will only work if Firefox ESR 52.x is used. </li><li class="listitem"> The <code class="literal">home-manager</code> tool now provides an <code class="literal">uninstall</code> sub-command that can be used to uninstall Home Manager, if used in the standalone mode. That is, not as a NixOS module. </li></ul></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="sec-release-19.09-state-version-changes"></a>E.4.2. State Version Changes</h3></div></div></div><p>The state version in this release includes the changes below. These changes are only active if the <code class="literal">home.stateVersion</code> option is set to "19.09" or later.</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"> The <a class="xref" href="options.html#opt-programs.firefox.package"><code class="option">programs.firefox.package</code></a> option now expects a wrapped Firefox package and defaults to <code class="literal">pkgs.firefox</code>. </li><li class="listitem"> The options <a class="xref" href="options.html#opt-home.keyboard.layout"><code class="option">home.keyboard.layout</code></a> and <a class="xref" href="options.html#opt-home.keyboard.variant"><code class="option">home.keyboard.variant</code></a> now default to <code class="literal">null</code>, which indicates that the system value should be used. </li></ul></div></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="sec-release-19.03"></a>E.5. Release 19.03</h2></div></div></div><p>The 19.03 release branch became the stable branch in April, 2019.</p><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="sec-release-19.03-highlights"></a>E.5.1. Highlights</h3></div></div></div><p>This release has the following notable changes:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p class="simpara"> The <a class="xref" href="options.html#opt-home.file._name_.source"><code class="option">home.file.<name>.source</code></a> option now allows source files to be hidden, that is, having a name starting with the <code class="literal">.</code> 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 </p><pre class="programlisting nix">home.file."my file".source = ./. + "/file with spaces!";</pre></li><li class="listitem"><p class="simpara"> The type used for the systemd unit options under <a class="xref" href="options.html#opt-systemd.user.services"><code class="option">systemd.user.services</code></a>, <a class="xref" href="options.html#opt-systemd.user.sockets"><code class="option">systemd.user.sockets</code></a>, 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. </p><p class="simpara">In particular, if you get an error saying that a “unique option” is “defined multiple times” then you need to use the <a class="link" href="https://nixos.org/nixos/manual/#sec-option-definitions-setting-priorities" target="_top"><code class="literal">mkForce</code></a> function. For example,</p><pre class="programlisting nix">systemd.user.services.foo.Service.ExecStart = "/foo/bar";</pre><p class="simpara">becomes</p><pre class="programlisting nix">systemd.user.services.foo.Service.ExecStart = lib.mkForce "/foo/bar";</pre><p class="simpara">We had to make this change because the old merging was causing too many confusing situations for people.</p></li></ul></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="sec-release-19.03-state-version-changes"></a>E.5.2. State Version Changes</h3></div></div></div><p>The state version in this release includes the changes below. These changes are only active if the <a class="xref" href="options.html#opt-home.stateVersion"><code class="option">home.stateVersion</code></a> option is set to “19.03” or later.</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"> There is now an option <a class="xref" href="options.html#opt-programs.beets.enable"><code class="option">programs.beets.enable</code></a> that defaults to <code class="literal">false</code>. Before the module would be active if the <a class="xref" href="options.html#opt-programs.beets.settings"><code class="option">programs.beets.settings</code></a> option was non-empty. </li></ul></div></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="sec-release-18.09"></a>E.6. Release 18.09</h2></div></div></div><p>The 18.09 release branch became the stable branch in September, 2018.</p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="tools.html">Prev</a> </td><td width="20%" align="center"> </td><td width="40%" align="right"> </td></tr><tr><td width="40%" align="left" valign="top">Appendix D. Tools </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> </td></tr></table></div></body></html>