Yazi

Yazi is a blazing-fast terminal file manager developed in Rust, using non-blocking async I/O for an efficient, user-friendly, and highly customizable file management experience. It features full asynchronous support, distributing CPU tasks across multiple threads to maximize resource use and improve performance.

It offers powerful async task scheduling with real-time progress updates, task cancellation, and internal prioritization. It supports multiple image protocols natively and integrates with Überzug++ for broad terminal compatibility. Additionally, Yazi includes built-in code highlighting and image decoding functionalities, along with a pre-loading mechanism to speed up file loading processes.

Installation

There are several ways to install Yazi on NixOS.

Temporary Shell

To temporarily use Yazi in your current shell session, run:

nix-shell -p yazi

System-wide

To install Yazi for all users on the system, add it to your configuration.nix:

programs.yazi.enable = true;

After adding the option, rebuild your system:

sudo nixos-rebuild switch

Home Manager

To install Yazi for a single user, add it to your Home Manager configuration:

programs.yazi.enable = true;

After adding the option, apply the changes:

home-manager switch

Configuration

As mentioned above, there are both NixOS options and home-manager options for configuring Yazi.

Advanced

programs.yazi = {
  enable = true;
  settings = {
    yazi = {
      ratio = [
        1
        4
        3
      ];
      sort_by = "natural";
      sort_sensitive = true;
      sort_reverse = false;
      sort_dir_first = true;
      linemode = "none";
      show_hidden = true;
      show_symlink = true;
    };

    preview = {
      image_filter = "lanczos3";
      image_quality = 90;
      tab_size = 1;
      max_width = 600;
      max_height = 900;
      cache_dir = "";
      ueberzug_scale = 1;
      ueberzug_offset = [
        0
        0
        0
        0
      ];
    };

    tasks = {
      micro_workers = 5;
      macro_workers = 10;
      bizarre_retry = 5;
    };
  };
}

Using separate files

If you would like to use your existing files to keep them portable, you can import them into your configuration directly to be read and built by nix.

❄︎ /etc/nixos/configuration.nix

programs.yazi = {
  enable = true;
  plugins = {
    inherit (pkgs.yaziPlugins) mount;
  };
  #initLua = ./init.lua
  settings = lib.importTOML ./yazi.toml; # yazi/yazi.toml
  keymap = lib.importTOML ./keymap.toml;
  theme = lib.importTOML ./theme.toml;      
};

Plugins

Installing Plugins

Many yazi plugins are packaged in nixpkgs.

There are some additional yazi plugins packaged in the nix-yazi-plugins flake. It also provides home-manager modules for configuring the plugins' options.

home-manager

❄︎ /etc/nixos/configuration.nix

programs.yazi = {
  enable = true;
  plugins = with pkgs.yaziPlugins; {
    # Plugins that don't call setup() can be configured in one line
    smart-enter.package = smart-enter;
    chmod.package = chmod;

    # Yatline-Catppuccin needs to be setup into a variable later
    yatline-catppuccin.package = yatline-catppuccin;    

    # Plugins with setup({settings})
    yatline = {
      package = yatline;
      setup = true;
      settings = {
        tab_width = 20;
        # Return as lua code
        theme = lib.mkLuaInline ''require("yatline-catppuccin"):setup("mocha")'';
      };
    };
  };
};

Flavors

With plugins = {} you can install plugins into your Yazi configuration directory (~/.config/yazi on unix-like systems by default). Similarly, when installing flavors or themes, use flavors = {}. For example:

flavors = {
  inherit (pkgs.yaziPlugins) kanagawa;
};
theme = {
  flavor = {
    dark = "kanagawa";
  };
};

Tips and tricks

Bleeding edge

The upstream repository provides a flake so that Nix users can easily keep up with the bleeding edge.

inputs = {
    yazi.url = "github:sxyazi/yazi";
};

Afterwards, you can use the new package.

# Global
environment.systemPackages = [ yazi.packages.${pkgs.stdenv.hostPlatform.system}.default ];
# or, if you use the module
programs.yazi.package = yazi.packages.${pkgs.stdenv.hostPlatform.system}.default;

# Home Manager
home.packages = [ yazi.packages.${pkgs.stdenv.hostPlatform.system}.default ];
# or, if you use the module
programs.yazi.package = yazi.packages.${pkgs.stdenv.hostPlatform.system}.default;

Pre-built artifacts are served at https://yazi.cachix.org, so that Nix users don't have to build Yazi on their machine.

nix = {
  settings = {
    substitute = true;
    substituters = [
      "https://yazi.cachix.org"
    ];
    trusted-public-keys = [
      "yazi.cachix.org-1:Dcdz63NZKfvUCbDGngQDAZq6kOroIrFoyO064uvLh8k="
    ];
  };
};

Stylix integration

theme = with config.stylix.base16Scheme; {
  filetype = {
    rules = [
      # Images
      {
        mime = "image/*";
        fg = "#${base0B}";
      }

      # Videos
      {
        mime = "video/*";
        fg = "#${base03}";
      }
      # Audio
      {
        mime = "audio/*";
        fg = "#${base08}";
      }
    ];
  };
};

Stylix can do it automatically for you if the following option is set:

stylix.targets.yazi.enable = true;

Key mapping

# Hyprland
bind = [
  "$mod, E, exec, kitty -e yazi"
];

Easy directory keymap

❄︎ /etc/nixos/configuration.nix

programs.yazi = {
  enable = true;
  keymap.mgr.prepend_keymap = [
      # Add your other keymaps here
    ] ++ lib.mapAttrsToList(dir: key: let 
      keys = if lib.isString key then [ "b" key ] else [ "b" ] ++ key;
    in {
      on = keys;
      run = ''cd ${dir}'';
      desc = ''Go to ${dir}'';
    }) {
      "/mnt/drive/" = "d";
      "~/.steam/steam/steamapps/" = ["s" "s"];
      "~/.steam/steam/steamapps/common" = ["s" "c"];
    };
};

Troubleshooting

RAR file extraction

By default, yazi depends on _7zz in nixpkgs for extraction and previewing purposes. This does not support RAR files by default. To enable support, you can override the _7zz in the dependencies into unfree rar version.

pkgs.yazi.override {_7zz = pkgs._7zz-rar; }

See also

• NixOS options for Yazi
• Yazi official documentation