Browse Files Visually in Your Terminal with Yazi

// Before you start

What you need

A terminal app (kitty, iTerm2, WezTerm, Ghostty, or Windows Terminal for image previews)
macOS, Linux, or Windows
A package manager: Homebrew (Mac/Linux), Scoop or Winget (Windows), or your Linux distro's package manager
Basic comfort typing commands into a terminal

Step 1 of 5

Install Yazi

3 min

Yazi is available through common package managers. Pick the one command that matches your system and paste it. Homebrew covers Mac and Linux. Scoop or Winget covers Windows. Your Linux distro may also have it natively.

Terminal · mac

$ # macOS or Linux with Homebrew:

$ brew install yazi

$ # Windows with Scoop:

$ scoop install yazi

$ # Windows with Winget:

$ winget install sxyazi.yazi

$ # Arch Linux:

$ pacman -S yazi

$ # Nix:

$ nix-env -iA nixpkgs.yazi

What you should see

Installation completes with no errors. You see a success message from your package manager.

This might happen

Command not found after install

Close your terminal and open a fresh one. The new PATH entry needs a restart to take effect.

Step 2 of 5

Install optional helper tools for better previews

3 min

Yazi can preview code with syntax highlighting, search files with ripgrep and fd, and jump to folders with fzf and zoxide. None of these are required to run Yazi, but they unlock its best features. Install as many as you like.

Terminal · mac

$ # macOS or Linux with Homebrew (installs all at once):

$ brew install ffmpegthumbnailer unar jq poppler fd ripgrep fzf zoxide imagemagick font-symbols-only-nerd-font

$ # Windows with Scoop:

$ scoop install unar jq fd ripgrep fzf zoxide

What you should see

Each tool installs without errors. It is fine to skip tools you do not need.

This might happen

One package fails on Linux because the name differs per distro

Search your distro's package manager for the tool by name, e.g. 'sudo apt search ripgrep'. Install what you can and skip the rest.

Step 3 of 5

Launch Yazi

1 min

Type the command below to open Yazi in your current directory. You will see a three-column layout: your directory tree on the left, files in the middle, and a live preview on the right. Use arrow keys or h/j/k/l (Vim-style) to move around. Press q to quit.

Terminal · mac

$ yazi

What you should see

A full-screen file browser appears inside your terminal showing your home directory split into three panels.

This might happen

The screen looks garbled or columns are misaligned

Your terminal font may lack the required symbols. Install a Nerd Font (https://www.nerdfonts.com) and set it as your terminal's font, then relaunch Yazi.

Step 4 of 5

Enable the shell wrapper so Yazi can change your directory on exit

2 min

By default, when you quit Yazi your terminal stays in the folder you started from. The official shell wrapper fixes this so your terminal jumps to whatever folder you were browsing when you pressed q. Add one line to your shell config file.

Terminal · mac

$ # For bash — add this line to ~/.bashrc:

$ echo '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"; }' >> ~/.bashrc && source ~/.bashrc

$ # For zsh — add this line to ~/.zshrc:

$ # For fish — add this to ~/.config/fish/config.fish:

$ echo 'function y; set tmp (mktemp -t "yazi-cwd.XXXXXX"); yazi $argv --cwd-file="$tmp"; if set cwd (command cat -- "$tmp"); and [ -n "$cwd" ]; and [ "$cwd" != "$PWD" ]; builtin cd -- "$cwd"; end; rm -f -- "$tmp"; end' >> ~/.config/fish/config.fish

What you should see

No output. The function is silently added. Now type 'y' instead of 'yazi' to launch it, and your terminal will follow you to the last folder you visited.

This might happen

Unsure which shell you use

Run 'echo $SHELL' in your terminal. If it says bash, use the bash command. If it says zsh, use the zsh command.

Step 5 of 5

Install a theme or plugin with the built-in package manager

2 min

Yazi has a package manager built in. You can browse community plugins and themes at https://github.com/yazi-rs/plugins. The command below installs the popular 'catppuccin' theme as an example. Replace the repo path with any plugin you want.

Terminal · mac

$ ya pack -a yazi-rs/flavors#catppuccin-mocha

What you should see

Yazi downloads and installs the theme. You will see a confirmation message. Restart Yazi to see the change.

This might happen

'ya' command not found

The 'ya' helper ships with Yazi but may not be in your PATH yet. Close and reopen your terminal, then try again. If it still fails, check that your package manager installed the full Yazi package and not just a partial one.

// Status

cooked. baked. worked.

A fast, keyboard-driven file manager running inside your terminal with live file previews, syntax-highlighted code, and optional image display. Typing 'y' opens it and drops you back in whatever folder you navigated to when you quit.

// the honest bit

The honest part

Yazi is in active development and breaking changes happen between versions. Image preview only works in supported terminals (kitty, iTerm2, WezTerm, Ghostty, Windows Terminal v1.22+, and others listed in the README). In a basic terminal like the default macOS Terminal.app, images will not display. The full plugin and theme ecosystem requires some manual config-file editing beyond what this guide covers — check the official docs at yazi-rs.github.io for advanced setup.