Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/sxyazi/yazi/llms.txt

Use this file to discover all available pages before exploring further.

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

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

​
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: 
[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

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
Distribution PackagesMost 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
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
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.
Add to your ~/.bashrc:
eval "$(ya completion bash)"

​
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

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"
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 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)
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

Build docs developers (and LLMs) love

Get started for freeTalk to us