Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Release 26.11

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 programs.uv module can now install uv-managed Python versions and tools through the new programs.uv.python.versions, programs.uv.python.default, and programs.uv.tool.packages options. Unpinned entries track the latest release on each activation while pinned ones stay put, and programs.uv.python.prune / programs.uv.tool.prune make the managed set fully declarative by removing versions and tools that are no longer listed.

  • On Darwin, Home Manager launchd agents now support launchd.agents.name.domain to choose either the user’s GUI or background launchd domain. Agents use the GUI domain by default. Set the domain to user for agents that should run without an active graphical login session.

  • The services.voxtype.enable daemon now starts as part of graphical-session.target instead of default.target. Starting after the compositor owns its GPU render node lets Vulkan-accelerated whisper builds detect their device. Previously, a daemon that started before the render node existed fell back to CPU and never recovered until it was restarted manually.

  • XSuspender now uses services.xsuspender.settings for freeform INI configuration. Move services.xsuspender.defaults to services.xsuspender.settings.Default and services.xsuspender.rules to services.xsuspender.settings.<name>. Use snake_case keys such as suspend_delay instead of suspendDelay.

    Deprecated aliases warn and preserve old defaults, including legacy function reads, in legacy sections and Default. These defaults have option-default priority, so ordinary assignments override them. Settings-only sections inherit from Default at runtime, then use native defaults. To preserve old behavior, set suspend_delay to 5 and only_on_battery to false, rather than 10 and true.

    Without legacy options, empty settings leave the configuration file unmanaged. If you configured both services.xsuspender.defaults and services.xsuspender.rules.Default, consolidate them under services.xsuspender.settings.Default. They now merge instead of the rule replacing the entire defaults section.

  • Notmuch now uses programs.notmuch.settings for native INI configuration. Deprecated options warn and map to settings, for example search.excludeTags to settings.search.exclude_tags. Home Manager no longer writes values notmuch already defaults to (new.tags, new.ignore, maildir.synchronize_flags); new.ignore order may differ.

    programs.notmuch.extraConfig no longer overwrites other definitions. Definitions follow module priorities: forced values win, lists concatenate, and ordinary scalar or string/list collisions fail. Use a list for extraConfig.new.ignore when mbsync, lieer, or mujmap contributes patterns. lib.mkForce on extraConfig replaces definitions in named sections. Section-level lib.mkDefault loses to sections Home Manager or sync modules define: database, new, search, and user. Null settings are omitted.

  • TWMN now uses services.twmn.settings for freeform INI configuration. Legacy options emit migration warnings. Move native options and extraConfig values into settings, resolving duplicate definitions. Enabling the service without configuration no longer creates a config file. Settings-only configurations use TWMN’s native defaults; see the option documentation for compatibility limits and preserving previous defaults.

  • Move programs.openstackclient.clouds to programs.openstackclient.cloudsSettings.clouds, and move programs.openstackclient.publicClouds to programs.openstackclient.cloudsPublicSettings.public-clouds. The old options remain as deprecated aliases and emit warnings.

  • Astroid now uses programs.astroid.settings for JSON configuration. Move programs.astroid.extraConfig into settings; replace externalEditor = "command" with settings.editor.cmd = "command" and settings.editor.external_editor = "true". Both old options warn; per-account astroid.extraConfig is unchanged. Home Manager no longer writes a full default configuration; Astroid’s built-in defaults match it except editor.markdown_processor, now cmark. Set settings.editor.markdown_processor = "marked" to keep marked. Without astroid accounts or settings, no config file is written.

    externalEditor merges at ordinary priority: differing ordinary editor keys conflict; lib.mkForce wins. Priorities on extraConfig sections apply as a unit. lib.mkForce on such a section drops its generated keys; lib.mkDefault loses for sections Home Manager defines. Prefer per-key priorities. Replacing a generated section with a non-object value requires lib.mkForce.

  • Grobi now uses services.grobi.settings for its complete JSON configuration. Move services.grobi.executeAfter to services.grobi.settings.execute_after and services.grobi.rules to services.grobi.settings.rules. The deprecated aliases preserve list order and definition priorities. The generated JSON is now pretty-printed.

  • Borgmatic backups now use programs.borgmatic.backups.name.settings for native YAML settings. Deprecated options warn with the backup name and move to their snake_case keys, such as retention.keepDaily to settings.keep_daily. Repository strings become { path = "..."; }, and each section’s extraConfig moves directly into settings. location.excludeHomeManagerSymlinks remains available.

    Legacy configurations without overlapping keys keep their generated YAML, except that null check frequencies are now omitted. Overlapping extraConfig keys no longer take the last section’s value. Distinct scalars at the same priority conflict and lists concatenate, so resolve overlaps in settings. Backups no longer need exactly one of sourceDirectories and patterns, which allows native patterns and database-only backups. repositories is still required.

  • programs.github-copilot-cli.settings is now written to settings.json instead of config.json, since Copilot CLI 1.0.35 and later keep user settings there and replace a linked config.json. The old link is removed on activation if it still points to a Home Manager generation; a regular state file is left alone. If Copilot CLI already created a regular settings.json from the old config.json, remove it before switching or enable programs.github-copilot-cli.mutableSettings to merge into it. With nonempty immutable settings, byte-identical files become managed links; differing files use normal collision and backup handling. Trusted folders in settings are no longer written, because Copilot CLI keeps them in its own state; declare them with programs.github-copilot-cli.trustedFolders 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 “26.11” or later.

  • On Darwin, the default value of programs.firefox.configPath changes from Library/Application Support/Firefox to Library/Application Support/org.nixos.firefox when programs.firefox.package is not null. Explicit configPath values remain unchanged. Users with a home.stateVersion earlier than "26.11" should set programs.firefox.configPath = "Library/Application Support/org.nixos.firefox"; explicitly. Before changing configPath, quit Firefox and move your data from ~/Library/Application Support/Firefox to ~/Library/Application Support/org.nixos.firefox.

  • From home.stateVersion = "26.11", notmuch no longer defaults search.exclude_tags to deleted;spam, and it sets database.path only when an email account is enabled. Earlier versions keep both defaults. To retain them when upgrading, set programs.notmuch.settings.search.exclude_tags = [ "deleted" "spam" ]; and, without email accounts, set programs.notmuch.settings.database.path to the mail directory, previously accounts.email.maildirBasePath.

  • The KDL options under programs.zellij will now correctly escape backslashes in string values. For example, the Nix string "\\" will now correctly generate the KDL string "\\". Previously, this would have generated "\", which is invalid KDL. The following options are affected:

    • programs.zellij.settings
    • programs.zellij.themes
    • programs.zellij.layouts

  • The KDL options under programs.zellij will now escape tabs in string values. For example, the Nix string "\t" (corresponding to a single tab) will now generate the KDL string "\t". Previously, this would have generated "<tab>" (where <tab> denotes a literal tab character). The following options are affected:

    • programs.zellij.settings
    • programs.zellij.themes
    • programs.zellij.layouts