How to Install Yazi on Debian: The Blazing Fast Terminal File Manager

Yazi is a blazing-fast terminal file manager written in Rust. Built on a fully asynchronous I/O model, it stays responsive even in enormous directories, renders image, video and PDF previews inline, and offers a Vim-like keyboard interface with multi-selection, tabs and a plugin system on top.

Yazi is young and iterating quickly, so the version in Debian’s official archive — if present at all — is typically well behind upstream, missing preview backends and plugin features that landed only recently. Installing from a release tarball works, but then every update becomes a manual chore.

The unofficial deb.griffo.io repository packages a current Yazi build you can install and update with apt. This guide covers the full process on Debian, including the shell wrapper that lets Yazi change your working directory.

What Makes Yazi Special?

  • ⚡ Fully asynchronous I/O — directory listing, preview loading and file tasks never block the UI.
  • 🖼️ Rich inline previews — images, videos, PDFs, archives and code with syntax highlighting, right in the terminal.
  • ⌨️ Vim-like navigation — hjkl movement, visual selection and familiar motions out of the box.
  • 🗂️ Tabs and bulk operations — juggle several directories and act on many files at once.
  • 🔌 Plugin and flavour system — extend behaviour and restyle the UI via Lua plugins and themes.
  • 🔍 Integrated finding — fuzzy jump with fzf and content search with ripgrep when installed.
  • 📋 System clipboard aware — yank, cut and paste files with an intuitive register model.
  • 🐚 Shell integration — the y wrapper changes your shell’s directory to wherever you left Yazi.

Why Use the deb.griffo.io Repository?

  • Easy installation and updates through the APT package manager.
  • Automatic dependency management handled by the Debian packaging.
  • Always tracks upstream releases so you get the latest Yazi.
  • No compiling from source and no Rust toolchain to set up.
  • Works across supported Debian releases — Bookworm, Trixie and Sid.

Prerequisites

Before starting, make sure you have:

  • A Debian-based system (Bookworm 12, Trixie 13, or Sid)
  • sudo privileges
  • curl installed (sudo apt install curl if needed)

Step 1: Add the deb.griffo.io Repository

Register the signing key and source list with these commands:

# Create the keyrings directory
sudo install -d -m 0755 /etc/apt/keyrings

# Download and install the repository GPG key
curl -fsSL https://deb.griffo.io/EA0F721D231FDD3A0A17B9AC7808B4DD62C41256.asc | sudo gpg --dearmor --yes -o /etc/apt/keyrings/deb.griffo.io.gpg

# Add the repository (auto-detects your distro codename)
echo "deb [signed-by=/etc/apt/keyrings/deb.griffo.io.gpg] https://deb.griffo.io/apt $(lsb_release -sc 2>/dev/null) main" | sudo tee /etc/apt/sources.list.d/deb.griffo.io.list > /dev/null

# Update the package list
sudo apt update

What each step does:

  1. Keyrings directory — creates /etc/apt/keyrings to hold third-party signing keys.
  2. GPG key — downloads and de-armours the repository key so APT can verify packages.
  3. Source list — adds the repository, detecting your Debian codename with lsb_release -sc.
  4. Update — refreshes the package index so Yazi becomes installable.

Step 2: Update the Package List

If you skipped the last command above, run:

sudo apt update

Step 3: Install Yazi

sudo apt install yazi

APT installs Yazi along with its runtime dependencies.

Step 4: Verify the Installation

yazi --version

You should see output resembling:

Yazi 25.5.31 (a1b2c3d 2025-05-31)

Launch the file manager itself by simply running:

yazi

Press q to quit at any time.

Getting Started with Yazi

Optional Preview Dependencies

Yazi’s inline previews and finders rely on a few external tools. Install the ones you want to enable full previews and fuzzy jumping:

sudo apt install ffmpegthumbnailer poppler-utils imagemagick fzf ripgrep fd-find jq
  • ffmpegthumbnailer — video thumbnails
  • poppler-utils — PDF previews
  • imagemagick — image handling for some formats
  • fzf — the fuzzy jump menu
  • ripgrep, fd-find — fast content and filename search
  • jq — pretty JSON previews

Core Navigation

Yazi’s default keys will feel familiar if you know Vim:

  • h / j / k / l — parent directory / down / up / enter directory
  • gg / G — jump to top / bottom
  • Space — toggle selection on the current file
  • v — visual (range) selection mode
  • y / x / p — yank (copy) / cut / paste
  • d — move to trash, D — delete permanently
  • a — create a file (end the name with / to make a directory)
  • r — rename, . — toggle hidden files
  • / — search, s — search by content, q — quit

Shell Integration (Change Directory on Exit)

By default, quitting Yazi leaves your shell in the directory you started from. To make your shell follow Yazi to wherever you finished, add this y wrapper function to ~/.bashrc:

function y() {
    local tmp="$(mktemp -t "yazi-cwd.XXXXXX")" cwd
    yazi "$@" --cwd-file="$tmp"
    if cwd="$(command cat -- "$tmp")" && [ -n "$cwd" ] && [ "$cwd" != "$PWD" ]; then
        builtin cd -- "$cwd"
    fi
    rm -f -- "$tmp"
}

Reload your shell and use y instead of yazi:

source ~/.bashrc
y

Now when you press q, your terminal stays in the last directory you browsed.

Configuration

Yazi reads its configuration from ~/.config/yazi/. Create the directory and start from the defaults you want to override:

mkdir -p ~/.config/yazi

The three main files are:

  • ~/.config/yazi/yazi.toml — general behaviour (sort order, preview settings, openers)
  • ~/.config/yazi/keymap.toml — custom key bindings
  • ~/.config/yazi/theme.toml — colours and appearance

A minimal yazi.toml that sorts directories first and shows hidden files:

[mgr]
sort_by     = "alphabetical"
sort_dir_first = true
show_hidden = true

Managing Plugins and Flavours

Yazi ships a companion CLI, ya, for managing plugins and themes. Define what you want in ~/.config/yazi/package.toml, then install:

# Install everything listed in package.toml
ya pkg install

# Add a plugin from a git repository
ya pkg add yazi-rs/plugins:full-border

# Upgrade all installed plugins and flavours
ya pkg upgrade

Keeping Yazi Updated

Because Yazi is installed via APT, updates come with your regular system upgrade:

sudo apt update && sudo apt upgrade

Other Tools from deb.griffo.io

The same repository packages many other terminal tools for Debian:

  • Helix — a post-modern modal text editor to open files from Yazi.
  • Zellij — a terminal workspace and multiplexer to run Yazi in a pane.
  • Lazydocker — a simple terminal UI for Docker and docker-compose.
  • Zig — a general-purpose systems programming language.

Troubleshooting

GPG or Key Errors

If APT reports that the repository cannot be verified, re-install the signing key:

sudo install -d -m 0755 /etc/apt/keyrings
curl -fsSL https://deb.griffo.io/EA0F721D231FDD3A0A17B9AC7808B4DD62C41256.asc | sudo gpg --dearmor --yes -o /etc/apt/keyrings/deb.griffo.io.gpg
sudo apt update

Package Not Found

If apt install yazi cannot locate the package:

  1. Run sudo apt update after adding the repository.
  2. Check your release is supported (Bookworm, Trixie or Sid).
  3. Verify the source list contents:
cat /etc/apt/sources.list.d/deb.griffo.io.list

Previews Are Blank

Empty previews almost always mean a helper program is missing. Confirm the relevant tools are installed and on your PATH:

command -v ffmpegthumbnailer pdftoppm magick

Note that on Debian fd is installed as fdfind by the fd-find package; if a plugin expects fd, symlink it:

sudo ln -s "$(command -v fdfind)" /usr/local/bin/fd

Uninstalling

# Remove the Yazi package
sudo apt remove yazi

# Optionally remove the repository
sudo rm -f /etc/apt/sources.list.d/deb.griffo.io.list
sudo rm -f /etc/apt/keyrings/deb.griffo.io.gpg
sudo apt update

Conclusion

Yazi turns the terminal into a fast, preview-rich file manager, and deb.griffo.io keeps it current on Debian without any manual downloads. Install it with apt, add the y shell wrapper, drop in a couple of preview dependencies, and you have a genuinely pleasant way to browse and manage files without leaving the keyboard.

Future releases — new preview backends, plugin APIs and performance work — arrive through the same apt upgrade you already run.

Resources

Disclaimer: The deb.griffo.io repository is an unofficial community project and is not affiliated with the official Debian or Ubuntu projects, or with the upstream Yazi project.