Installation

Install Yazi on Linux, macOS, Windows, or build from source

Yazi is available through multiple package managers and can also be built from source. Choose the installation method that works best for your platform.

Package Managers

Cargo (Rust)

Install via Cargo (Rust’s package manager):

cargo install --locked --git https://github.com/sxyazi/yazi.git yazi-fm yazi-cli

Due to Cargo’s limitations, you must use cargo install --locked --git (not cargo install yazi-fm) to build from the repository. The crates on crates.io require cargo install --force yazi-build due to workspace constraints.

Or install a specific version from crates.io:

cargo install --locked --force yazi-build

Homebrew (macOS/Linux)

Install via Homebrew:

brew install yazi

This installs both yazi (the file manager) and ya (the command-line interface).

Arch Linux

Install from the official repositories:

sudo pacman -S yazi

Or install the development version from AUR:

yay -S yazi-git

Nix/NixOS

Install via Nix:

nix-env -iA nixpkgs.yazi

Or add to your NixOS configuration:

environment.systemPackages = [ pkgs.yazi ];

For development, use the flake:

nix develop github:sxyazi/yazi

Scoop (Windows)

Install via Scoop on Windows:

scoop install yazi

Snap

Install via Snap (Linux):

snap install yazi

Building from Source

Yazi is written in Rust. To build from source, you’ll need the Rust toolchain installed.

1. Install Rust

   If you don’t have Rust installed, get it from rustup.rs:

   curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
   
2. Clone the Repository

   Clone the Yazi repository from GitHub:

   git clone https://github.com/sxyazi/yazi.git
   cd yazi
   
3. Build the Project

   Build both the file manager and CLI tool:

   cargo build --release --locked
   

   The compiled binaries will be in target/release/:

   • yazi - The file manager
   • ya - The CLI tool
4. Install the Binaries

   Copy the binaries to your system:

   sudo cp target/release/yazi /usr/local/bin/
   sudo cp target/release/ya /usr/local/bin/
   

   Or install directly with cargo:

   cargo install --path yazi-fm --locked
   cargo install --path yazi-cli --locked
   

Build Profiles

The project includes several build profiles in Cargo.toml:

Release (Optimized)

[profile.release]
codegen-units = 1
lto = true
panic = "abort"
strip = true

To build with a specific profile:

cargo build --profile release-windows

Platform-Specific Notes

macOS

Homebrew (Recommended)

brew install yazi

Requirements:

• macOS 10.15+ (Catalina or later)
• Terminal with true color support

Terminal Recommendations:

• kitty - Best image preview support (Kitty protocol)
• iTerm2 - Built-in inline images protocol
• WezTerm - Cross-platform with image support

Linux

Distribution Packages

Most major distributions have Yazi in their repositories:

# Arch Linux
sudo pacman -S yazi

# Fedora
sudo dnf install yazi

# Ubuntu/Debian (via snap)
snap install yazi

Requirements:

• glibc 2.31+ (or musl)
• Terminal with true color support

Optional Dependencies:

• file - Better file type detection
• ffmpegthumbnailer - Video thumbnails
• unar - Archive preview
• jq - JSON preview
• fd - Fast file search
• ripgrep - Fast content search
• fzf - Fuzzy finder integration
• zoxide - Directory jumping

Windows

Scoop (Recommended)

scoop install yazi

Requirements:

• Windows 10+ (build 18363 or later for best results)
• Windows Terminal (recommended) or another terminal with ANSI support

Notes:

• Image preview support is limited compared to Unix systems
• Use Windows Terminal for the best experience
• Some Unix-specific features may not be available

Android (Termux)

Install via Termux package manager:

pkg install yazi

Or build from source:

pkg install rust git
cargo install --locked --git https://github.com/sxyazi/yazi.git yazi-fm yazi-cli

Shell Integration

Yazi includes a CLI tool (ya) that supports shell completions.

Bash

Add to your ~/.bashrc:

eval "$(ya completion bash)"

Zsh

Add to your ~/.zshrc:

eval "$(ya completion zsh)"

Fish

Add to your Fish configuration:

ya completion fish | source

Or save to a file:

ya completion fish > ~/.config/fish/completions/ya.fish

Nushell

Generate completions:

ya completion nushell > ~/.config/nushell/completions/ya.nu

Then source it in your Nushell config.

PowerShell

Add to your PowerShell profile:

ya completion powershell | Out-String | Invoke-Expression

Verify Installation

After installation, verify that Yazi is working correctly:

1. Check Version

   yazi --version
   

   You should see output like:

   yazi 26.2.2
   
2. Check CLI Tool

   ya --version
   

   Verify the CLI tool is also installed.

3. Launch Yazi

   yazi
   

   Yazi should open in your current directory. Press q to quit.

Installation Complete! You’re ready to start using Yazi. Continue to the Quickstart Guide to learn the basics.

Troubleshooting

Command not found

If you get a “command not found” error:

1. Make sure the installation completed successfully
2. Check that the binary is in your PATH:
   which yazi
   
3. If installed via cargo, add ~/.cargo/bin to your PATH:
   export PATH="$HOME/.cargo/bin:$PATH"
   

Colors not displaying correctly

Yazi requires a terminal with true color (24-bit color) support.

Test your terminal:

echo $COLORTERM

It should output truecolor or 24bit. If not:

• Use a modern terminal emulator (kitty, iTerm2, WezTerm, Windows Terminal)
• Set the COLORTERM environment variable:
  export COLORTERM=truecolor
  

Image previews not working

Image preview support depends on your terminal. See the Image Preview documentation for detailed setup instructions.

Quick check - your terminal protocol:

• kitty: Full support built-in
• iTerm2/WezTerm: Full support built-in
• Foot/Windows Terminal: Sixel support built-in
• Other terminals: Use Überzug++ (X11/Wayland) or Chafa (fallback)

Build errors

Common build issues:

1. Rust version too old: Update Rust:

   rustup update stable
   

2. Missing system dependencies: Install build essentials:

   # Ubuntu/Debian
   sudo apt install build-essential
   
   # Fedora
   sudo dnf install gcc
   
   # macOS
   xcode-select --install
   

3. Workspace build issues: Always use --locked and build from git:

   cargo install --locked --git https://github.com/sxyazi/yazi.git yazi-fm yazi-cli
   

Next Steps

Quickstart Guide

Learn the basics in under 2 minutes

Configuration

Customize Yazi to match your workflow

Keybindings

Learn all keyboard shortcuts

Image Preview

Set up image previews for your terminal