Configuring a terminal environment with Home Manager

Configuring Zsh with Nix#

Home Manager provides powerful programs.zsh options that let you manage all your plugins in Nix code.

{ pkgs, lib, ... }: {
  programs.zsh = {
    enable = true;
    enableCompletion = true;
    autosuggestion.enable = true;
    syntaxHighlighting.enable = true;

    # 别名 (Aliases)
    shellAliases = {
      ll = "ls -l";
      build-system = "nixos-rebuild build --flake .#my-host";
    };

    # 插件 (Plugins)
    plugins = [
      {
        name = "zsh-nix-shell";
        file = "nix-shell.plugin.zsh";
        src = pkgs.fetchFromGitHub {
          owner = "chisui";
          repo = "zsh-nix-shell";
          rev = "v0.8.0";
          hash = lib.fakeHash; # 占位；首次构建核验来源后填写实际固定输出 hash
        };
      }
    ];

    # 自定义 .zshrc 内容
    initExtra = ''
      export PATH=$HOME/.bin:$PATH
    '';
  };
}

The prompt: Starship#

If you like a modern terminal prompt, configuration is straightforward:

{
  programs.starship = {
    enable = true;
    # 这里可以自定义 starship.toml
    settings = {
      add_newline = false;
      character = {
        success_symbol = "[➜](bold green)";
        error_symbol = "[➜](bold red)";
      };
    };
  };
}

Common command-line tools (CLI)#

These tools also have dedicated configuration options in Home Manager:

• programs.git: Configure your username, email address, and aliases.
• programs.fzf: Automatically enable Zsh bindings.
• programs.direnv: Automatically load the development environment when you enter a directory.
• programs.bat: A cat with syntax highlighting.

Why do this?#

1. Ready to use: Clone your configuration on a new machine and run a command to install all your shell plugins and themes automatically.
2. Reusable configuration: You can easily put your Zsh configuration in a separate file and share it across machines, even on macOS.

Migration tip#

At the configuration.nix level, you only need to specify users.defaultUserShell = pkgs.zsh;; leave all the shell details to Home Manager.

Version compatibility and shell responsibilities#

The example retains the initExtra syntax from older Home Manager versions; newer versions may use initContent. Verify plugin versions and hashes against the actual pinned sources rather than treating placeholders as validated configuration. The system layer also needs to enable programs.zsh.enable and set the user’s login shell; Home Manager manages the user configuration.