> ## 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.

# 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

<Tabs>
  <Tab title="Cargo (Rust)">
    Install via Cargo (Rust's package manager):

    ```bash theme={null}
    cargo install --locked --git https://github.com/sxyazi/yazi.git yazi-fm yazi-cli
    ```

    <Note>
      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.
    </Note>

    Or install a specific version from crates.io:

    ```bash theme={null}
    cargo install --locked --force yazi-build
    ```
  </Tab>

  <Tab title="Homebrew (macOS/Linux)">
    Install via Homebrew:

    ```bash theme={null}
    brew install yazi
    ```

    This installs both `yazi` (the file manager) and `ya` (the command-line interface).
  </Tab>

  <Tab title="Arch Linux">
    Install from the official repositories:

    ```bash theme={null}
    sudo pacman -S yazi
    ```

    Or install the development version from AUR:

    ```bash theme={null}
    yay -S yazi-git
    ```
  </Tab>

  <Tab title="Nix/NixOS">
    Install via Nix:

    ```bash theme={null}
    nix-env -iA nixpkgs.yazi
    ```

    Or add to your NixOS configuration:

    ```nix theme={null}
    environment.systemPackages = [ pkgs.yazi ];
    ```

    For development, use the flake:

    ```bash theme={null}
    nix develop github:sxyazi/yazi
    ```
  </Tab>

  <Tab title="Scoop (Windows)">
    Install via Scoop on Windows:

    ```powershell theme={null}
    scoop install yazi
    ```
  </Tab>

  <Tab title="Snap">
    Install via Snap (Linux):

    ```bash theme={null}
    snap install yazi
    ```
  </Tab>
</Tabs>

## Building from Source

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

<Steps>
  <Step title="Install Rust">
    If you don't have Rust installed, get it from [rustup.rs](https://rustup.rs):

    ```bash theme={null}
    curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
    ```
  </Step>

  <Step title="Clone the Repository">
    Clone the Yazi repository from GitHub:

    ```bash theme={null}
    git clone https://github.com/sxyazi/yazi.git
    cd yazi
    ```
  </Step>

  <Step title="Build the Project">
    Build both the file manager and CLI tool:

    ```bash theme={null}
    cargo build --release --locked
    ```

    The compiled binaries will be in `target/release/`:

    * `yazi` - The file manager
    * `ya` - The CLI tool
  </Step>

  <Step title="Install the Binaries">
    Copy the binaries to your system:

    ```bash theme={null}
    sudo cp target/release/yazi /usr/local/bin/
    sudo cp target/release/ya /usr/local/bin/
    ```

    Or install directly with cargo:

    ```bash theme={null}
    cargo install --path yazi-fm --locked
    cargo install --path yazi-cli --locked
    ```
  </Step>
</Steps>

### Build Profiles

The project includes several build profiles in `Cargo.toml`:

<CodeGroup>
  ```toml Release (Optimized) theme={null}
  [profile.release]
  codegen-units = 1
  lto = true
  panic = "abort"
  strip = true
  ```

  ```toml Release Windows theme={null}
  [profile.release-windows]
  inherits = "release"
  panic = "unwind"
  ```

  ```toml Development (Faster builds) theme={null}
  [profile.dev-opt]
  inherits = "release"
  codegen-units = 256
  incremental = true
  lto = false
  ```
</CodeGroup>

To build with a specific profile:

```bash theme={null}
cargo build --profile release-windows
```

## Platform-Specific Notes

<AccordionGroup>
  <Accordion title="macOS" icon="apple">
    **Homebrew (Recommended)**

    ```bash theme={null}
    brew install yazi
    ```

    **Requirements**:

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

    **Terminal Recommendations**:

    * [kitty](https://sw.kovidgoyal.net/kitty/) - Best image preview support (Kitty protocol)
    * [iTerm2](https://iterm2.com) - Built-in inline images protocol
    * [WezTerm](https://wezfurlong.org/wezterm/) - Cross-platform with image support
  </Accordion>

  <Accordion title="Linux" icon="linux">
    **Distribution Packages**

    Most major distributions have Yazi in their repositories:

    ```bash theme={null}
    # 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
  </Accordion>

  <Accordion title="Windows" icon="windows">
    **Scoop (Recommended)**

    ```powershell theme={null}
    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
  </Accordion>

  <Accordion title="Android (Termux)" icon="mobile">
    Install via Termux package manager:

    ```bash theme={null}
    pkg install yazi
    ```

    Or build from source:

    ```bash theme={null}
    pkg install rust git
    cargo install --locked --git https://github.com/sxyazi/yazi.git yazi-fm yazi-cli
    ```
  </Accordion>
</AccordionGroup>

## Shell Integration

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

<Tabs>
  <Tab title="Bash">
    Add to your `~/.bashrc`:

    ```bash theme={null}
    eval "$(ya completion bash)"
    ```
  </Tab>

  <Tab title="Zsh">
    Add to your `~/.zshrc`:

    ```bash theme={null}
    eval "$(ya completion zsh)"
    ```
  </Tab>

  <Tab title="Fish">
    Add to your Fish configuration:

    ```bash theme={null}
    ya completion fish | source
    ```

    Or save to a file:

    ```bash theme={null}
    ya completion fish > ~/.config/fish/completions/ya.fish
    ```
  </Tab>

  <Tab title="Nushell">
    Generate completions:

    ```bash theme={null}
    ya completion nushell > ~/.config/nushell/completions/ya.nu
    ```

    Then source it in your Nushell config.
  </Tab>

  <Tab title="PowerShell">
    Add to your PowerShell profile:

    ```powershell theme={null}
    ya completion powershell | Out-String | Invoke-Expression
    ```
  </Tab>
</Tabs>

## Verify Installation

After installation, verify that Yazi is working correctly:

<Steps>
  <Step title="Check Version">
    ```bash theme={null}
    yazi --version
    ```

    You should see output like:

    ```
    yazi 26.2.2
    ```
  </Step>

  <Step title="Check CLI Tool">
    ```bash theme={null}
    ya --version
    ```

    Verify the CLI tool is also installed.
  </Step>

  <Step title="Launch Yazi">
    ```bash theme={null}
    yazi
    ```

    Yazi should open in your current directory. Press `q` to quit.
  </Step>
</Steps>

<Check>
  **Installation Complete!** You're ready to start using Yazi. Continue to the [Quickstart Guide](quickstart) to learn the basics.
</Check>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Command not found" icon="triangle-exclamation">
    If you get a "command not found" error:

    1. Make sure the installation completed successfully
    2. Check that the binary is in your PATH:
       ```bash theme={null}
       which yazi
       ```
    3. If installed via cargo, add `~/.cargo/bin` to your PATH:
       ```bash theme={null}
       export PATH="$HOME/.cargo/bin:$PATH"
       ```
  </Accordion>

  <Accordion title="Colors not displaying correctly" icon="palette">
    Yazi requires a terminal with true color (24-bit color) support.

    Test your terminal:

    ```bash theme={null}
    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:
      ```bash theme={null}
      export COLORTERM=truecolor
      ```
  </Accordion>

  <Accordion title="Image previews not working" icon="image">
    Image preview support depends on your terminal. See the [Image Preview](features/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)
  </Accordion>

  <Accordion title="Build errors" icon="hammer">
    Common build issues:

    1. **Rust version too old**: Update Rust:
       ```bash theme={null}
       rustup update stable
       ```

    2. **Missing system dependencies**: Install build essentials:
       ```bash theme={null}
       # 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:
       ```bash theme={null}
       cargo install --locked --git https://github.com/sxyazi/yazi.git yazi-fm yazi-cli
       ```
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Quickstart Guide" icon="play" href="quickstart">
    Learn the basics in under 2 minutes
  </Card>

  <Card title="Configuration" icon="gear" href="configuration/overview">
    Customize Yazi to match your workflow
  </Card>

  <Card title="Keybindings" icon="keyboard" href="usage/keybindings">
    Learn all keyboard shortcuts
  </Card>

  <Card title="Image Preview" icon="image" href="features/image-preview">
    Set up image previews for your terminal
  </Card>
</CardGroup>