### NixGL Configuration Example

Source: https://nix-community.github.io/home-manager/index.xhtml

Configure NixGL packages, default and offload wrappers, and install script names. This example demonstrates wrapping mpv for the primary GPU, FreeCAD for the secondary Nvidia GPU, and Xonotic for the secondary Nvidia GPU using direct wrapper function.

```nix
{ config, lib, pkgs, nixgl, ... }:
{
  targets.genericLinux.nixGL = {
    packages = nixgl.packages;
    defaultWrapper = "mesa";
    offloadWrapper = "nvidiaPrime";
    installScripts = [ "mesa" "nvidiaPrime" ];
  };

  programs.mpv = {
    enable = true;
    package = config.lib.nixGL.wrap pkgs.mpv;
  };

  home.packages = [
    (config.lib.nixGL.wrapOffload pkgs.freecad)
    (config.lib.nixGL.wrappers.nvidiaPrime pkgs.xonotic)
  ];
}

```

--------------------------------

### NixOS User Configuration Example

Source: https://nix-community.github.io/home-manager/index.xhtml

Example NixOS configuration snippet for setting up a user's environment with Home Manager. It includes enabling Bash and installing packages.

```nix
users.users.eve.isNormalUser = true;
home-manager.users.eve = { pkgs, ... }:
{
  home.packages = [ pkgs.atool pkgs.httpie ];
  programs.bash.enable = true;

  # This value determines the Home Manager release that your configuration is
  # compatible with. This helps avoid breakage when a new Home Manager release
  # introduces backwards incompatible changes.
  #
  # You should not change this value, even if you update Home Manager. If you do
  # want to update the value, then make sure to first check the Home Manager
  # release notes.
  home.stateVersion = "25.11"; # Please read the comment before changing.

};

```

--------------------------------

### Declarative Home Manager Installation (NixOS)

Source: https://nix-community.github.io/home-manager/index.xhtml

Declaratively installs Home Manager using `configuration.nix`. This example configures user 'eve' with specific packages and Bash settings.

```nix
{ config, pkgs, lib, ... }:

let
  home-manager = builtins.fetchTarball https://github.com/nix-community/home-manager/archive/release-25.11.tar.gz;
in
{
  imports =
    [
      (import "${home-manager}/nixos")
    ];

  users.users.eve.isNormalUser = true;
  home-manager.users.eve = { pkgs, ... }: {
    home.packages = [ pkgs.atool pkgs.httpie ];
    programs.bash.enable = true;

    # The state version is required and should stay at the version you
    # originally installed.
    home.stateVersion = "25.11";
  };
}

```

--------------------------------

### NixGL Configuration with Channels

Source: https://nix-community.github.io/home-manager/index.xhtml

This example shows how to import NixGL packages when using channels instead of flakes. The rest of the configuration remains the same as the flake-based setup.

```nix
{ config, lib, pkgs, ... }:
{
  targets.genericLinux.nixGL.packages = import <nixgl> { inherit pkgs; };
  # The rest is the same as above
  ...

}

```

--------------------------------

### Nix-darwin Configuration Example

Source: https://nix-community.github.io/home-manager/index.xhtml

Example of a nix-darwin configuration that includes Home Manager settings for a user, specifying packages and program configurations.

```nix
users.users.eve = {
  name = "eve";
  home = "/Users/eve";
};
home-manager.users.eve = { pkgs, ... }: {
  home.packages = [ pkgs.atool pkgs.httpie ];
  programs.bash.enable = true;

  # The state version is required and should stay at the version you
  # originally installed.
  home.stateVersion = "25.11";
};
```

--------------------------------

### Install Home Manager (Standalone)

Source: https://nix-community.github.io/home-manager/index.xhtml

Runs the Home Manager installation command to create the first generation. This command activates Home Manager in your user environment.

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

--------------------------------

### Install Home Manager

Source: https://nix-community.github.io/home-manager/release-notes.xhtml

Use this command to install Home Manager. The initial configuration will automatically include necessary options when switching to state version 20.09.

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

```

--------------------------------

### Define Home Manager packages

Source: https://nix-community.github.io/home-manager/index.xhtml

Example configuration snippet for declaring packages in Home Manager.

```nix
home.packages = [ pkgs.hello ];
```

--------------------------------

### Define Home Manager Configuration

Source: https://nix-community.github.io/home-manager/index.xhtml

Example of a home.nix file configuring packages, Emacs, and GPG agent services.

```nix
{ config, pkgs, ... }:

{
  # Home Manager needs a bit of information about you and the
  # paths it should manage.
  home.username = "jdoe";
  home.homeDirectory = "/home/jdoe";

  # Packages that should be installed to the user profile.
  home.packages = [
    pkgs.htop
    pkgs.fortune
  ];

  # This value determines the Home Manager release that your
  # configuration is compatible with. This helps avoid breakage
  # when a new Home Manager release introduces backwards
  # incompatible changes.
  #
  # You can update Home Manager without changing this value. See
  # the Home Manager release notes for a list of state version
  # changes in each release.
  home.stateVersion = "25.11";

  # Let Home Manager install and manage itself.
  programs.home-manager.enable = true;

  programs.emacs = {
    enable = true;
    extraPackages = epkgs: [
      epkgs.nix-mode
      epkgs.magit
    ];
  };

  services.gpg-agent = {
    enable = true;
    defaultCacheTtl = 1800;
    enableSshSupport = true;
  };
}
```

--------------------------------

### Display Home Manager Channel URL

Source: https://nix-community.github.io/home-manager/index.xhtml

Example output showing the Home Manager channel URL.

```text
home-manager https://github.com/nix-community/home-manager/archive/release-24.11.tar.gz

```

--------------------------------

### Git Configuration File Example

Source: https://nix-community.github.io/home-manager/index.xhtml

Example of the generated git configuration file based on the Home Manager Nix code. This file is typically located at ~/.config/git/config.

```ini
[user]
	email = "joe@example.org"
	name = "joe"

```

--------------------------------

### Basic Home Manager Test Structure

Source: https://nix-community.github.io/home-manager/index.xhtml

This example shows the basic structure of a Home Manager test file using the NMT framework. It includes defining program settings and NMT assertions for file existence and content.

```nix
{
  # Home Manager configuration
  programs.myprogram = {
    enable = true;
    settings = {
      option = "value";
    };
  };

  # NMT test script with assertions
  nmt.script = ''
    assertFileExists "home-files/.config/myprogram/config.toml"
    assertFileContent "home-files/.config/myprogram/config.toml" ${./expected-config.toml}
  '';
}

```

--------------------------------

### Add Home Manager Channel (Release 25.11)

Source: https://nix-community.github.io/home-manager/index.xhtml

Adds the Home Manager release-25.11 channel for standalone installation. Ensure Nix is installed and your user can build packages.

```bash
$ nix-channel --add https://github.com/nix-community/home-manager/archive/release-25.11.tar.gz home-manager
$ nix-channel --update
```

--------------------------------

### Invalid configuration example

Source: https://nix-community.github.io/home-manager/index.xhtml

An example of an incorrect configuration value that triggers a type error during the build process.

```nix
programs.emacs.enable = "yes";

```

--------------------------------

### Add Home Manager Channel (Master)

Source: https://nix-community.github.io/home-manager/index.xhtml

Adds the Home Manager master channel for standalone installation. Ensure Nix is installed and your user can build packages.

```bash
$ nix-channel --add https://github.com/nix-community/home-manager/archive/master.tar.gz home-manager
$ nix-channel --update
```

--------------------------------

### Module Argument Example

Source: https://nix-community.github.io/home-manager/index.xhtml

Home Manager passes `osConfig` as a module argument, containing the system's NixOS configuration.

```nix
{ lib, pkgs, osConfig, ... }:
```

--------------------------------

### Query installed packages

Source: https://nix-community.github.io/home-manager/index.xhtml

Check currently installed packages in the user environment.

```bash
$ nix-env --query
hello-2.10
```

--------------------------------

### Handle Configuration Collisions

Source: https://nix-community.github.io/home-manager/index.xhtml

Example of a configuration that might conflict with existing files and the resulting error message.

```nix
{
  # …

  programs.git = {
    enable = true;
    userName = "Jane Doe";
    userEmail = "jane.doe@example.org";
  };

  # …
}
```

```bash
$ home-manager switch
…
Activating checkLinkTargets
Existing file '/home/jdoe/.config/git/config' is in the way
Please move the above files and try again
```

--------------------------------

### Enable Home Manager uninstall in Nix Flake setup

Source: https://nix-community.github.io/home-manager/release-notes.xhtml

To clean up a Home Manager installation using a pure Nix Flake setup, add `uninstall = true;` to your configuration and then build and activate. Be cautious as this will remove all managed files and Home Manager state.

```nix
uninstall = true;
```

--------------------------------

### Verify Home Manager Version

Source: https://nix-community.github.io/home-manager/index.xhtml

Check the installed version of the Home Manager tool.

```bash
$ home-manager --version

```

--------------------------------

### Module Directory Structure

Source: https://nix-community.github.io/home-manager/index.xhtml

Example of the directory layout for Home Manager modules, showing which files are automatically imported and which are excluded.

```text
modules/programs/
├── git.nix              # Single-file module (imported)
├── firefox/             # Multi-file module (imported)
│   ├── default.nix
│   └── addons.nix
├── _experimental.nix    # Excluded (starts with _)
└── _wip/                # Excluded directory (starts with _)
    └── newfeature.nix
```

--------------------------------

### Configure Sway/i3 Bars with Waybar

Source: https://nix-community.github.io/home-manager/release-notes.xhtml

Example of configuring the `bars` option for Sway or i3 window managers to use Waybar. This demonstrates how to set a custom bar command.

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

```

--------------------------------

### Minimal home.nix configuration

Source: https://nix-community.github.io/home-manager/index.xhtml

A template for a fresh Home Manager installation, defining the username, home directory, state version, and self-management.

```nix
{ config, pkgs, ... }:

{
  # Home Manager needs a bit of information about you and the
  # paths it should manage.
  home.username = "jdoe";
  home.homeDirectory = "/home/jdoe";

  # This value determines the Home Manager release that your
  # configuration is compatible with. This helps avoid breakage
  # when a new Home Manager release introduces backwards
  # incompatible changes.
  #
  # You can update Home Manager without changing this value. See
  # the Home Manager release notes for a list of state version
  # changes in each release.
  home.stateVersion = "25.11";

  # Let Home Manager install and manage itself.
  programs.home-manager.enable = true;
}

```

--------------------------------

### Add Shared Modules to All Users

Source: https://nix-community.github.io/home-manager/nix-darwin-options.xhtml

Provide a list of extra modules to be added to all users. Example includes adding `nixpkgs-fmt` to `home.packages`.

```nix
[ ]

```

```nix
[ { home.packages = [ nixpkgs-fmt ]; } ]

```

--------------------------------

### Verify Home Manager Channel

Source: https://nix-community.github.io/home-manager/index.xhtml

List currently configured Nix channels to identify the Home Manager installation source.

```bash
$ nix-channel --list

```

--------------------------------

### GPU driver setup command

Source: https://nix-community.github.io/home-manager/index.xhtml

Command displayed by the activation script when GPU drivers require an update on non-NixOS systems.

```bash
Activating checkExistingGpuDrivers
GPU drivers require an update, run
  sudo /nix/store/HASH-non-nixos-gpu/bin/non-nixos-gpu-setup
```

--------------------------------

### Specify Backup Command

Source: https://nix-community.github.io/home-manager/nix-darwin-options.xhtml

Provide a command to run on existing files during activation instead of exiting with an error. Example uses `trash-cli`.

```nix
null
```

```nix
${pkgs.trash-cli}/bin/trash
```

--------------------------------

### Configure Nixpkgs Path for State Version >= 20.09

Source: https://nix-community.github.io/home-manager/release-notes.xhtml

If you need to retain the use of `<nixpkgs>` with state version 20.09 or later, add this configuration to your Home Manager setup.

```nix
_module.args.pkgsPath = <nixpkgs>;

```

--------------------------------

### Install Packages from Nixpkgs Unstable

Source: https://nix-community.github.io/home-manager/index.xhtml

Import Nixpkgs unstable to access its packages. Ensure the 'nixpkgs-unstable' channel is added and updated.

```nix
{ pkgs, config, ... }:

let

  pkgsUnstable = import <nixpkgs-unstable> {};

in

{
  home.packages = [
    pkgsUnstable.foo
  ];

  # …
}

```

--------------------------------

### Update and Switch Flake Configuration

Source: https://nix-community.github.io/home-manager/index.xhtml

Commands to update flake inputs and apply the configuration for standalone setups.

```bash
$ nix flake update
$ home-manager switch --flake .

```

--------------------------------

### Default Sway/i3 Bar Configuration (Pre-20.09 Behavior)

Source: https://nix-community.github.io/home-manager/release-notes.xhtml

This is an example of the extensive default configuration for Sway/i3 bars that was present before state version 20.09. It includes settings for font, mode, position, status command, and color schemes.

```nix
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
  }

}

```

--------------------------------

### Pass Extra Special Arguments

Source: https://nix-community.github.io/home-manager/nix-darwin-options.xhtml

Pass additional arguments to all Home Manager modules. Example shows inheriting an `emacs-overlay`.

```nix
{ }

```

```nix
{ inherit emacs-overlay; }

```

--------------------------------

### Enable User Packages in Nix-darwin

Source: https://nix-community.github.io/home-manager/index.xhtml

Set this option to true in your nix-darwin configuration to install user packages to `/etc/profiles/per-user/$USERNAME`.

```nix
home-manager.useUserPackages = true;
```

--------------------------------

### New Module News Entry Example

Source: https://nix-community.github.io/home-manager/index.xhtml

A typical news entry for a new module should announce its availability. Platform-specific modules can include a condition.

```text
A new module is available: 'services.foo'.

```

```nix
condition = hostPlatform.isLinux;

```

--------------------------------

### Allowing Hidden Source Files in home.file

Source: https://nix-community.github.io/home-manager/release-notes.xhtml

The `home.file._name_.source` option now supports source files with names starting with a dot (`.`) and names containing characters not typically allowed in Nix store paths. This allows for more flexible file sourcing.

```nix
home.file."my file".source = ./. + "/file with spaces!";

```

--------------------------------

### Initialize Home Manager with Custom Directory

Source: https://nix-community.github.io/home-manager/index.xhtml

Initialize Home Manager configuration in a custom directory, and activate it using the specified path.

```bash
$ nix run home-manager/$branch -- init --switch ~/hmconf

```

```bash
$ # And after the initial activation.

```

```bash
$ home-manager switch --flake ~/hmconf

```

--------------------------------

### Build HTML Documentation

Source: https://nix-community.github.io/home-manager/index.xhtml

Generate the HTML version of the Home Manager manual from a local clone. This is useful for reviewing documentation changes.

```bash
$ nix-build -A docs.html
$ xdg-open ./result/share/doc/home-manager/index.xhtml

```

--------------------------------

### Initialize Home Manager Standalone (Release)

Source: https://nix-community.github.io/home-manager/index.xhtml

Use this command to generate and activate a basic Home Manager configuration for the 25.11 release of Nixpkgs or NixOS.

```bash
$ nix run home-manager/release-25.11 -- init --switch

```

--------------------------------

### Initialize nix-darwin template

Source: https://nix-community.github.io/home-manager/index.xhtml

Command to generate a new nix-darwin configuration using the Home Manager template.

```bash
$ nix flake new ~/.config/darwin -t github:nix-community/home-manager#nix-darwin
```

--------------------------------

### Accessing configuration documentation

Source: https://nix-community.github.io/home-manager/index.xhtml

Command to view the manual for Home Manager configuration options in the terminal.

```bash
man home-configuration.nix

```

--------------------------------

### Home Manager switch error output

Source: https://nix-community.github.io/home-manager/index.xhtml

Example of a collision error encountered during a switch operation.

```bash
$ home-manager switch
these derivations will be built:
  /nix/store/xg69wsnd1rp8xgs9qfsjal017nf0ldhm-home-manager-path.drv
[…]
Activating installPackages
replacing old ‘home-manager-path’
installing ‘home-manager-path’
building path(s) ‘/nix/store/b5c0asjz9f06l52l9812w6k39ifr49jj-user-environment’
Wide character in die at /nix/store/64jc9gd2rkbgdb4yjx3nrgc91bpjj5ky-buildenv.pl line 79.
collision between ‘/nix/store/fmwa4axzghz11cnln5absh31nbhs9lq1-home-manager-path/bin/hello’ and ‘/nix/store/c2wyl8b9p4afivpcz8jplc9kis8rj36d-hello-2.10/bin/hello’; use ‘nix-env --set-flag priority NUMBER PKGNAME’ to change the priority of one of the conflicting packages
builder for ‘/nix/store/b37x3s7pzxbasfqhaca5dqbf3pjjw0ip-user-environment.drv’ failed with exit code 2
error: build of ‘/nix/store/b37x3s7pzxbasfqhaca5dqbf3pjjw0ip-user-environment.drv’ failed
```

--------------------------------

### Enable X server in system configuration

Source: https://nix-community.github.io/home-manager/index.xhtml

Required system-level configuration to allow Home Manager to manage graphical services.

```nix
{
  # …

  services.xserver.enable = true;

  # …
}
```

--------------------------------

### Configure Syncthing Tray Service

Source: https://nix-community.github.io/home-manager/release-notes.xhtml

The `services.syncthing.tray` option is now expected to be configured using `services.syncthing.tray.enable` to enable the Syncthing tray service. The previous boolean option has been removed.

```nix
services.syncthing.tray.enable = true;

```

--------------------------------

### Initialize Home Manager Standalone (Unstable)

Source: https://nix-community.github.io/home-manager/index.xhtml

Run this command to generate and activate a basic Home Manager configuration using the master branch of Home Manager.

```bash
$ nix run home-manager/master -- init --switch

```

--------------------------------

### Uninstall GPU drivers

Source: https://nix-community.github.io/home-manager/index.xhtml

Commands to manually remove the GPU driver setup and associated systemd services.

```bash
sudo rm /run/opengl-driver
sudo systemctl disable --now non-nixos-gpu.service
sudo rm /etc/systemd/system/non-nixos-gpu.service
```

--------------------------------

### Apply Home Manager Changes

Source: https://nix-community.github.io/home-manager/index.xhtml

Activate the current Home Manager configuration.

```bash
$ home-manager switch

```

--------------------------------

### Activate Home Manager Configuration

Source: https://nix-community.github.io/home-manager/index.xhtml

Commands to apply or build the current configuration.

```bash
home-manager switch
```

```bash
home-manager build
```

--------------------------------

### Create NixOS Configuration from Template

Source: https://nix-community.github.io/home-manager/index.xhtml

Use this command to create a new NixOS configuration directory using the Home Manager NixOS module template.

```bash
$ nix flake new /etc/nixos -t github:nix-community/home-manager#nixos

```

--------------------------------

### Manually Import Home Manager Modules

Source: https://nix-community.github.io/home-manager/release-notes.xhtml

For advanced users seeking to optimize evaluation time, enable `home-manager.minimal` and manually import required modules. This approach requires maintaining a personal list of modules.

```nix
imports = [
    "${modulesPath}/programs/fzf.nix"
  ];

```

--------------------------------

### Configure Qt platform theme and style

Source: https://nix-community.github.io/home-manager/release-notes.xhtml

The Qt module now supports specifying a theme name and package for `qt.style`. If `qt.platformTheme` is set to `gnome`, a compatible `qt.style.package` is required.

```nix
qt = {
  platformTheme = "gnome";
  style = {
    name = "adwaita-dark";
    package = pkgs.adwaita-qt;
  };
};


```

--------------------------------

### News Entry Deprecation Example

Source: https://nix-community.github.io/home-manager/index.xhtml

When referring to deprecated options in news entries, always use the full attribute path for clarity.

```text
The option 'foo' has been deprecated, please use 'bar' instead.

```

```text
The option 'services.myservice.foo' has been deprecated, please
use 'services.myservice.bar' instead.

```

--------------------------------

### Migrate home.file configuration

Source: https://nix-community.github.io/home-manager/release-notes.xhtml

Update deprecated list-based file definitions to the preferred attribute set format.

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

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

--------------------------------

### Configure custom mpv package with VapourSynth support

Source: https://nix-community.github.io/home-manager/release-notes.xhtml

Allows custom derivations for `programs.mpv.package`, enabling features like VapourSynth support by wrapping the mpv package.

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

```

--------------------------------

### Basic NixOS flake.nix for Home Manager

Source: https://nix-community.github.io/home-manager/index.xhtml

A minimal `flake.nix` to integrate Home Manager as a NixOS module. Ensure `home-manager.inputs.nixpkgs.follows` is set correctly.

```nix
{
  description = "NixOS configuration";

  inputs = {
    nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable";
    home-manager.url = "github:nix-community/home-manager";
    home-manager.inputs.nixpkgs.follows = "nixpkgs";
  };

  outputs = inputs@{ nixpkgs, home-manager, ... }:
    {
      nixosConfigurations = {
        hostname = nixpkgs.lib.nixosSystem {
          system = "x86_64-linux";
          modules = [
            ./configuration.nix
            home-manager.nixosModules.home-manager
            {
              home-manager.useGlobalPkgs = true;
              home-manager.useUserPackages = true;
              home-manager.users.jdoe = ./home.nix;

              # Optionally, use home-manager.extraSpecialArgs to pass
              # arguments to home.nix
            }
          ];
        };
      };
    };
}

```

--------------------------------

### Import nix-darwin Module

Source: https://nix-community.github.io/home-manager/index.xhtml

Import the Home Manager nix-darwin module into your nix-darwin configuration.nix file.

```nix
imports = [ <home-manager/nix-darwin> ];
```

--------------------------------

### Enable Legacy Profile Management

Source: https://nix-community.github.io/home-manager/nixos-options.xhtml

Controls whether to enable legacy profile management during activation. When enabled, Home Manager creates a per-user Nix profile similar to standalone installations. Typically not desired when Home Manager is embedded in the system configuration.

```nix
false
```

--------------------------------

### Build Man Pages Documentation

Source: https://nix-community.github.io/home-manager/index.xhtml

Generate the man page version of the Home Manager module options from a local clone. This is helpful for checking the formatting and content of man pages.

```bash
$ nix-build -A docs.manPages
$ man ./result/share/man/man5/home-configuration.nix.5.gz

```

--------------------------------

### Configure rofi theme using attribute set

Source: https://nix-community.github.io/home-manager/release-notes.xhtml

The `programs.rofi.theme` option now supports defining a theme using an attribute set, allowing for more complex configurations including importing other theme files.

```nix
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";
  };
};


```

--------------------------------

### Enable Global Nixpkgs Instance

Source: https://nix-community.github.io/home-manager/index.xhtml

Set this option to true to use the global Nixpkgs instance instead of Home Manager's private instance. This saves an evaluation and removes the NIX_PATH dependency.

```nix
home-manager.useGlobalPkgs = true;
```

--------------------------------

### Specify Backup Command for Home Manager Activation

Source: https://nix-community.github.io/home-manager/nixos-options.xhtml

Defines a command to run on existing files during Home Manager activation instead of exiting with an error. This is useful for custom backup or trash behaviors.

```nix
${pkgs.trash-cli}/bin/trash
```

--------------------------------

### Test exact file content

Source: https://nix-community.github.io/home-manager/index.xhtml

Compares generated configuration files against an expected reference file.

```nix
{
  programs.fastfetch = {
    enable = true;
    settings.display.color = "blue";
  };

  nmt.script =
    let
      configFile = "home-files/.config/fastfetch/config.jsonc";
    in
    ''
      assertFileExists "${configFile}"
      assertFileContent "${configFile}" ${./expected-config.jsonc}
    '';
```

--------------------------------

### Configure Local Home Manager Path

Source: https://nix-community.github.io/home-manager/index.xhtml

Set the path to a local clone of Home Manager within your configuration. This ensures that `home-manager switch` and `home-manager build` commands use your local version.

```nix
programs.home-manager.enable = true;
programs.home-manager.path = "$HOME/devel/home-manager";

```

--------------------------------

### Enable Legacy Profile Management in Home Manager

Source: https://nix-community.github.io/home-manager/release-notes.xhtml

To restore the previous behavior of creating a per-user 'shadow profile', set `home-manager.enableLegacyProfileManagement` to `true` in your configuration. This option may be deprecated in the future.

```nix
home-manager.enableLegacyProfileManagement = true;

```

--------------------------------

### Enable Experimental Features in nix.conf

Source: https://nix-community.github.io/home-manager/index.xhtml

Configure your `nix.conf` file to enable experimental features for Nix command and flakes when not using NixOS.

```nix
experimental-features = nix-command flakes

```

--------------------------------

### Configure htop settings

Source: https://nix-community.github.io/home-manager/release-notes.xhtml

The `programs.htop.settings` option replaces individual options for htop configuration, allowing direct setting of htop options.

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


```

--------------------------------

### Configure Home Manager with Flakes

Source: https://nix-community.github.io/home-manager/index.xhtml

Define Home Manager inputs and outputs within a flake.nix file.

```nix
{
  description = "Home Manager configuration";

  inputs = {
    # Increment release branch for NixOS
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-25.05";
    home-manager = {
      # Follow corresponding `release` branch from Home Manager
      url = "github:nix-community/home-manager/release-25.05";
      inputs.nixpkgs.follows = "nixpkgs";
    };
  };

  outputs = { nixpkgs, home-manager, ... }: {
    homeConfigurations."yourusername" = home-manager.lib.homeManagerConfiguration {
      pkgs = nixpkgs.legacyPackages.x86_64-linux;
      modules = [ ./home.nix ];
    };
  };
}

```

--------------------------------

### Use Local Home Manager Clone (CLI Override)

Source: https://nix-community.github.io/home-manager/index.xhtml

Temporarily use a local clone of Home Manager by overriding the input path via the command line. This is useful for quick testing of changes.

```bash
$ home-manager -I home-manager=$HOME/devel/home-manager

```

--------------------------------

### Enable Experimental Features in NixOS

Source: https://nix-community.github.io/home-manager/index.xhtml

Add these settings to your `configuration.nix` to enable experimental features for Nix command and flakes on NixOS.

```nix
nix.settings.experimental-features = "nix-command flakes";

```

--------------------------------

### Use Unstable Package via Overlay

Source: https://nix-community.github.io/home-manager/index.xhtml

Enable a module and override its package using a Nixpkgs overlay to point to the unstable version.

```nix
{ pkgs, config, ... }:

let

  pkgsUnstable = import <nixpkgs-unstable> {};

in

{
  programs.skim.enable = true;

  nixpkgs.overlays = [
    (self: super: {
      skim = pkgsUnstable.skim;
    })
  ];

  # …
}

```

--------------------------------

### Enable X session in Home Manager

Source: https://nix-community.github.io/home-manager/index.xhtml

Required Home Manager configuration to enable X session management.

```nix
{
  # …

  xsession.enable = true;
  xsession.windowManager.command = "…";

  # …
}
```

--------------------------------

### Multi-machine configuration template

Source: https://nix-community.github.io/home-manager/index.xhtml

Structure for a top-level configuration file that imports common settings.

```nix
{ ... }:

{
  imports = [ ./common.nix ];

  # Various options that are specific for this machine/user.
}
```

--------------------------------

### Configure flake-parts with Home Manager

Source: https://nix-community.github.io/home-manager/index.xhtml

Integrates Home Manager into a flake-parts configuration by importing the flake module.

```nix
{
  description = "flake-parts configuration";

  inputs = {
    nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable";
    home-manager.url = "github:nix-community/home-manager";
    home-manager.inputs.nixpkgs.follows = "nixpkgs";
    flake-parts.url = "github:hercules-ci/flake-parts";
  };

  outputs = inputs@{
    flake-parts,
    home-manager,
    nixpkgs,
    ...
  }:
    flake-parts.lib.mkFlake { inherit inputs; } {
      imports = [
        # Import home-manager's flake module
        inputs.home-manager.flakeModules.home-manager
      ];
      flake = {
        # Reusable Home Manager module.
        homeModules.bash= { pkgs, ... }: {
          programs.bash = {
            enable = true;
            shellAliases = {
              ll = "ls -l";
            };
          };
          home.packages = [ pkgs.hello ];
        };

        # Concrete Home Manager configuration.
        homeConfigurations.alice = home-manager.lib.homeManagerConfiguration {
          pkgs = import nixpkgs { system = "x86_64-linux"; };
          modules = [
            inputs.self.homeModules.bash
            {
              home.username = "alice";
              home.homeDirectory = "/home/alice";
              home.stateVersion = "25.11";
            }
          ];
        };
      };
      # See flake.parts for more features, such as `perSystem`
    };
}
```

--------------------------------

### Set Backup File Extension

Source: https://nix-community.github.io/home-manager/nix-darwin-options.xhtml

Define a file extension to append to existing files when backing them up during activation. Defaults to null.

```nix
null
```

```nix
"backup"
```

--------------------------------

### Home Manager Configuration Options

Source: https://nix-community.github.io/home-manager/nix-darwin-options.xhtml

A collection of configuration options for managing Home Manager profiles, backups, and module integration within nix-darwin.

```APIDOC
## Home Manager Configuration Options

### Description
These options allow users to configure how Home Manager behaves when integrated into a nix-darwin system configuration.

### Parameters
- **home-manager.enableLegacyProfileManagement** (boolean) - Optional - Whether to enable legacy profile management during activation. Default: false.
- **home-manager.backupCommand** (null|string|path) - Optional - Command to run on existing files during activation instead of exiting with an error.
- **home-manager.backupFileExtension** (null|string) - Optional - File extension to append to existing files during activation.
- **home-manager.extraSpecialArgs** (attribute set) - Optional - Extra arguments passed to all Home Manager modules.
- **home-manager.minimal** (boolean) - Optional - Whether to enable only necessary modules. Default: false.
- **home-manager.overwriteBackup** (boolean) - Optional - Whether to force overwrite existing backup files. Default: false.
- **home-manager.sharedModules** (list) - Optional - Extra modules added to all users.
- **home-manager.useGlobalPkgs** (boolean) - Optional - Whether to use the system configuration's pkgs argument. Default: false.
- **home-manager.useUserPackages** (boolean) - Optional - Whether to install user packages through users.users.<name>.packages. Default: false.
- **home-manager.users** (attribute set) - Optional - Per-user Home Manager configuration.
- **home-manager.verbose** (boolean) - Optional - Whether to enable verbose output on activation. Default: false.
```

--------------------------------

### Initialize Home Manager Without Activation

Source: https://nix-community.github.io/home-manager/index.xhtml

Generate Home Manager configuration files without immediate activation, allowing for inspection and editing.

```bash
$ nix run home-manager/$branch -- init

```

```bash
$ # Edit files in ~/.config/home-manager

```

```bash
$ nix run home-manager/$branch -- init --switch

```

--------------------------------

### Configure nix-darwin with Home Manager

Source: https://nix-community.github.io/home-manager/index.xhtml

Defines a flake.nix file to integrate Home Manager into a nix-darwin system configuration.

```nix
{
  description = "Darwin configuration";

  inputs = {
    nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable";
    darwin.url = "github:nix-darwin/nix-darwin";
    darwin.inputs.nixpkgs.follows = "nixpkgs";
    home-manager.url = "github:nix-community/home-manager";
    home-manager.inputs.nixpkgs.follows = "nixpkgs";
  };

  outputs = inputs@{ nixpkgs, home-manager, darwin, ... }: {
    darwinConfigurations = {
      hostname = darwin.lib.darwinSystem {
        system = "x86_64-darwin";
        modules = [
          ./configuration.nix
          home-manager.darwinModules.home-manager
          {
            home-manager.useGlobalPkgs = true;
            home-manager.useUserPackages = true;
            home-manager.users.jdoe = ./home.nix;

            # Optionally, use home-manager.extraSpecialArgs to pass
            # arguments to home.nix
          }
        ];
      };
    };
  };
}
```

--------------------------------

### Source Home Manager Session Variables (System Packages)

Source: https://nix-community.github.io/home-manager/index.xhtml

Source this file in your shell configuration if Home Manager is not managing your shell and `home-manager.useUserPackages` is not enabled.

```bash
. "/etc/profiles/per-user/$USER/etc/profile.d/hm-session-vars.sh"
```

--------------------------------

### Add Home Manager NixOS Module Channel (Release 25.11)

Source: https://nix-community.github.io/home-manager/index.xhtml

Adds the Home Manager release-25.11 channel for NixOS module integration. This command must be run as root.

```bash
$ sudo nix-channel --add https://github.com/nix-community/home-manager/archive/release-25.11.tar.gz home-manager
$ sudo nix-channel --update
```

--------------------------------

### Enable Experimental Features Per Command

Source: https://nix-community.github.io/home-manager/index.xhtml

Use these flags with `nix` and `home-manager` commands to enable experimental features on a per-command basis.

```bash
$ nix --extra-experimental-features "nix-command flakes" <sub-commands>

```

```bash
$ home-manager --extra-experimental-features "nix-command flakes" <sub-commands>

```

--------------------------------

### Enable Git Configuration

Source: https://nix-community.github.io/home-manager/index.xhtml

Enables Git configuration for a user, setting the user name and email. This snippet configures the git program within Home Manager.

```nix
programs.git = {
  enable = true;
  userEmail = "joe@example.org";
  userName = "joe";
};

```

--------------------------------

### Configure font with name and size

Source: https://nix-community.github.io/home-manager/release-notes.xhtml

The `fontType` library now includes a `size` attribute in addition to `name` for font configuration.

```nix
font = {
  name = "DejaVu Sans";
  size = 8;
};


```

--------------------------------

### Run tests via CLI

Source: https://nix-community.github.io/home-manager/index.xhtml

Commands for discovering and executing tests using the nix run interface.

```bash
# List all available tests
$ nix run .#tests -- -l

# List tests matching a pattern
$ nix run .#tests -- -l alacritty

# Run all tests matching a pattern
$ nix run .#tests -- alacritty

# Run a specific test
$ nix run .#tests -- test-alacritty-empty-settings

# Run integration tests
$ nix run .#tests -- -t -l

# Interactive test selection (requires fzf)
$ python3 tests/tests.py -i

# Pass additional nix build flags
$ nix run .#tests -- alacritty -- --verbose
```

--------------------------------

### Set Backup File Extension for Home Manager

Source: https://nix-community.github.io/home-manager/nixos-options.xhtml

Specifies a file extension to append to existing files during Home Manager activation, used for backups instead of exiting with an error. Set to null to disable this feature.

```nix
"backup"
```

--------------------------------

### Test configuration file generation

Source: https://nix-community.github.io/home-manager/index.xhtml

Verifies that a specific configuration file exists and contains expected content.

```nix
{
  programs.alacritty = {
    enable = true;
    settings.font.size = 12;
  };

  nmt.script = ''
    assertFileExists "home-files/.config/alacritty/alacritty.yml"
    assertFileContains "home-files/.config/alacritty/alacritty.yml" "size: 12"
  '';
}
```

--------------------------------

### Configure Nvidia drivers in Home Manager

Source: https://nix-community.github.io/home-manager/index.xhtml

Configuration block for specifying Nvidia driver version and hash in Home Manager.

```nix
targets.genericLinux.gpu.nvidia = {
  enable = true;
  version = "550.163.01";
  sha256 = "sha256-74FJ9bNFlUYBRen7+C08ku5Gc1uFYGeqlIh7l1yrmi4=";
};
```

--------------------------------

### Use Local Home Manager Clone (Flakes Override)

Source: https://nix-community.github.io/home-manager/index.xhtml

Use a local clone of Home Manager with flakes by overriding the input path. This method is suitable when working with Home Manager's flake integration.

```bash
$ home-manager --override-input home-manager ~/devel/home-manager

```

--------------------------------

### Per-User Home Manager Configuration

Source: https://nix-community.github.io/home-manager/nix-darwin-options.xhtml

Attribute set for per-user Home Manager configuration. Defaults to an empty set.

```nix
{ }

```

--------------------------------

### Pass Extra Special Arguments to Home Manager

Source: https://nix-community.github.io/home-manager/nixos-options.xhtml

Allows passing additional arguments to all Home Manager modules. This is useful for injecting custom configurations or dependencies.

```nix
{ inherit emacs-overlay; }
```

--------------------------------

### Prefetch Nvidia driver

Source: https://nix-community.github.io/home-manager/index.xhtml

Command to fetch and calculate the hash for proprietary Nvidia drivers.

```bash
nix store prefetch-file \
  https://download.nvidia.com/XFree86/Linux-x86_64/550.163.01/NVIDIA-Linux-x86_64-550.163.01.run
```

--------------------------------

### Add Home Manager NixOS Module Channel (Master)

Source: https://nix-community.github.io/home-manager/index.xhtml

Adds the Home Manager master channel for NixOS module integration. This command must be run as root.

```bash
$ sudo nix-channel --add https://github.com/nix-community/home-manager/archive/master.tar.gz home-manager
$ sudo nix-channel --update
```

--------------------------------

### Add Shared Modules to All Users in Home Manager

Source: https://nix-community.github.io/home-manager/nixos-options.xhtml

Specifies a list of extra modules to be added to all users' Home Manager configurations. This allows for common configurations across multiple users.

```nix
[ { home.packages = [ nixpkgs-fmt ]; } ]
```

--------------------------------

### Enable Minimal Home Manager Configuration

Source: https://nix-community.github.io/home-manager/nixos-options.xhtml

Enables only the essential modules required for Home Manager to function. This is for advanced users and disables almost all modules, requiring manual management of module lists.

```nix
true
```

--------------------------------

### Import Home Manager NixOS Module

Source: https://nix-community.github.io/home-manager/index.xhtml

Imports the Home Manager NixOS module into your system configuration. This makes the `home-manager.users` option available.

```nix
imports = [ <home-manager/nixos> ];
```

--------------------------------

### Set Home Manager State Version

Source: https://nix-community.github.io/home-manager/index.xhtml

Define the state version in your configuration to ensure backward compatibility.

```nix
{
  home.stateVersion = "24.11";  # Example: if you first installed on 24.11
}

```

--------------------------------

### Enable Minimal Home Manager Functionality

Source: https://nix-community.github.io/home-manager/nix-darwin-options.xhtml

Set to true to enable only the essential modules for Home Manager to function. This is for advanced users and disables almost all modules. Use with caution.

```nix
false
```

```nix
true
```

--------------------------------

### Set Home Manager State Version

Source: https://nix-community.github.io/home-manager/release-notes.xhtml

The `home.stateVersion` option no longer has a default value. Explicitly set it to your desired version, e.g., "18.09", if not already specified.

```nix
home.stateVersion = "18.09";
```

--------------------------------

### Test Case Organization in default.nix

Source: https://nix-community.github.io/home-manager/index.xhtml

This Nix expression demonstrates how to organize multiple test cases for a module within a `default.nix` file, mapping test names to their respective files.

```nix
{
  myprogram-basic-configuration = ./basic-configuration.nix;
  myprogram-empty-settings = ./empty-settings.nix;
}

```

--------------------------------

### Update programs.pet.settings Syntax

Source: https://nix-community.github.io/home-manager/release-notes.xhtml

Illustrates the change in how `programs.pet.settings.editor` is defined. This change affects configurations for versions 21.11 and later.

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

```nix
programs.pet.settings.General.editor = "nvim";
```

--------------------------------

### Deprecated neomutt binds/macros string format

Source: https://nix-community.github.io/home-manager/release-notes.xhtml

Specifying `programs.neomutt.binds.map` or `programs.neomutt.macros.map` as a single string is deprecated. Use a list of strings instead.

```nix
configure.packages.*.opt  -> programs.neovim.plugins = [ { plugin = ...; optional = true; }]
configure.packages.*.start  -> programs.neovim.plugins = [ { plugin = ...; }]
configure.customRC -> programs.neovim.extraConfig


```

--------------------------------

### Source Home Manager Session Variables (System)

Source: https://nix-community.github.io/home-manager/index.xhtml

Sources the Home Manager session variables script from the system profile. Use this when managing Home Manager configuration alongside system configuration.

```bash
/etc/profiles/per-user/$USER/etc/profile.d/hm-session-vars.sh
```

--------------------------------

### Migrate programs.ssh.matchBlocks to DAG entries

Source: https://nix-community.github.io/home-manager/release-notes.xhtml

Replace deprecated list-based SSH match blocks with DAG entries to maintain configuration order.

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

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