Zsh: Difference between revisions

Latest revision as of 00:48, 14 May 2025

Zsh is a powerful Unix shell that functions both as an interactive shell and a scripting language interpreter. It extends the Bourne Shell (sh) with features from bash, ksh, and tcsh, offering advanced tab completion, improved globbing, and extensive customization options. Though not POSIX sh-compatible by default, it can be configured to be so with emulate sh.

Key features include highly customizable prompts, enhanced command history, spelling correction, and robust job control. The Oh My Zsh framework simplifies managing plugins and themes. Zsh is cross-platform, available on Unix-like systems including Linux and macOS, and is popular among developers and system administrators for its advanced features and user-friendly enhancements.

The Zsh FAQ offers more reasons to use Zsh.

Installation

NixOS system installation

To install zsh for a user on a regular nixos system:

❄︎ /etc/nixos/configuration.nix

  programs.zsh.enable = true;
  users.extraUsers.myuser = {
    ...
    shell = pkgs.zsh;
  };

Replace myuser with the appropriate username.

See Command Shell for more information.

Home Manager

For a user-specific installation managed by Home Manager, use the following configuration:

❄︎ home.nix

  home-manager.users.myuser = {
    programs.zsh.enable = true;
  };

Replace myuser with the appropriate username.

You can enable the zsh shell and manage zsh configuration and plugins with Home Manager, but to enable vendor zsh completions provided by Nixpkgs you will also want to enable the zsh shell:

❄︎ /etc/nixos/configuration.nix

  programs.zsh.enable = true;

Configuration

NixOS system configuration

The following example demonstrates how to configure zsh system-wide through the NixOS configuration:

❄︎ /etc/nixos/configuration.nix

  programs.zsh = {
    enable = true;
    enableCompletion = true;
    autosuggestions.enable = true;
    syntaxHighlighting.enable = true;

    shellAliases = {
      ll = "ls -l";
      edit = "sudo -e";
      update = "sudo nixos-rebuild switch";
    };

    histSize = 10000;
    histFile = "$HOME/.zsh_history";
    setOptions = [
      "HIST_IGNORE_ALL_DUPS"
    ];
  };

For a full list of zsh module options, refer to programs.zsh.

Plugins

The most straightforward way to manage Zsh plugins on NixOS is by enabling the ohMyZsh plugin manager, as demonstrated in the example below:

❄︎ /etc/nixos/configuration.nix

  programs.zsh = {
    enable = true;
    ohMyZsh = {
      enable = true;
      plugins = [
        "git"
        "z"
      ];
      theme = "robbyrussell";
    };
  };

Alternatively, individual Zsh plugins are available as zsh-* packages within Nixpkgs. When using this method, plugins must be manually sourced within the Zsh configuration file.

Home Manager

The configuration below is using Home Manager, but a more limited version of it can be achieved if system-wide.

❄︎ home.nix

  programs.zsh = {
    enable = true;
    enableCompletion = true;
    autosuggestion.enable = true;
    syntaxHighlighting.enable = true;

    shellAliases = {
      ll = "ls -l";
      edit = "sudo -e";
      update = "sudo nixos-rebuild switch";
    };

    history.size = 10000;
    history.ignoreAllDups = true;
    history.path = "$HOME/.zsh_history";
    history.ignorePatterns = ["rm *" "pkill *" "cp *"];
  };

The home manager options are defined in the following Home Manager Options Manual or can be looked up at Home Manager Option Search.

The system-wide options are listed on programs.zsh.*.

Plugins

Home manager has four ways of managing plugins: Zplug, Oh-My-Zsh, Antidote and manually.

❄︎ home.nix

programs.zsh = {
  enable = true;

# With Zplug:
  zplug = {
    enable = true;
    plugins = [
      {name = "zsh-users/zsh-autosuggestions";} # Simple plugin installation
      {
        name = "romkatv/powerlevel10k";
        tags = [ "as:theme" "depth:1" ];
      } # Installations with additional options. For the list of options, please refer to Zplug README.
    ];
  };

# With Oh-My-Zsh:
  oh-my-zsh = {
    enable = true;
    plugins = [
      "git"         # also requires `programs.git.enable = true;`
      "thefuck"     # also requires `programs.thefuck.enable = true;` 
    ];
    theme = "robbyrussell";
  };

# With Antidote:
  antidote = {
    enable = true;
    plugins = [''
      zsh-users/zsh-autosuggestions
      ohmyzsh/ohmyzsh path:lib/git.zsh
    '']; # explanation of "path:..." and other options explained in Antidote README.

# Manual
  plugins = [
    {
      name = "zsh-autocomplete";
      src = pkgs.fetchFromGitHub {
        owner = "marlonrichert";
        repo = "zsh-autocomplete";
        rev = "23.07.13";
        sha256 = "sha256-/6V6IHwB5p0GT1u5SAiUa20LjFDSrMo731jFBq/bnpw=";
      };
    }
    {
      name = "powerlevel10k";
      src = pkgs.zsh-powerlevel10k;
      file = "share/zsh-powerlevel10k/powerlevel10k.zsh-theme";
    }
    {
      name = "powerlevel10k-config";
      src = ./p10k-config;
      file = "p10k.zsh";
    }
    {
      name = "zsh-syntax-highlighting";
      src = pkgs.fetchFromGitHub {
        owner = "zsh-users";
        repo = "zsh-syntax-highlighting";
        rev = "0.8.0";
        sha256 = "sha256-iJdWopZwHpSyYl5/FQXEW7gl/SrKaYDEtTH9cGP7iPo=";
      };
    }
  ];
};

An example of less verbatim approach to sourcing packaged plugins can be found here and here.

Troubleshooting

Zsh-autocomplete not working

You may have some issues with the marlonrichert/zsh-autocomplete plugin on NixOS. That's because the default NixOS configuration overrides keybinds for up and down arrow keys. To fix this issue, you need to add this somewhere in your .zshrc (either manually if your .zshrc is not managed by Nix, or with packages.zsh.initExtra)

bindkey "''${key[Up]}" up-line-or-search

SHA Mismatch during manual plugin installation

If manual plugin installation fails with SHA mismatch, generating a valid hash as part of the error message can be achieved by temporarily switching to:

sha256 = lib.fakeSha256;

This will print a valid SHA to the console and then can be used as final value for the sha256 field. Redoing this is mandatory if one wants to update to a newer commit of the targeted plugin repository.

GDM does not show user when zsh is the default shell

GDM only shows users that have their default shell set to a shell listed in /etc/shells. Setting the default shell using the following does not update /etc/shells.

users.defaultUserShell = pkgs.zsh;

To add the zsh package to /etc/shells you must update environment.shells.

environment.shells = with pkgs; [ zsh ];

Hide configuration for new users

Meaning this message:

This is the Z Shell configuration function for new users,
zsh-newuser-install.
You are seeing this message because you have no zsh startup files
(the files .zshenv, .zprofile, .zshrc, .zlogin in the directory
~).  This function can help you with a few settings that should
make your use of the shell easier.

You can:

(q)  Quit and do nothing.  The function will be run again next time.

(0)  Exit, creating the file ~/.zshrc containing just a comment.
     That will prevent this function being run again.

(1)  Continue to the main menu.

--- Type one of the keys in parentheses ---

You can hide this message by adding following line to the system configuration:

# Prevent the new user dialog in zsh
system.userActivationScripts.zshrc = "touch .zshrc";

References