---
title: "How to install and configure Yazi on Hyprland"
description: "How to install and configure Yazi, the fast Rust-based terminal file manager, on Hyprland - including Kitty integration and using Yazi as a file picker."
url: "https://knng.de/blog/hyprland-yazi/"
published: "2025-11-21"
updated: "2026-04-26"
series: "Arch Linux and Hyprland on a Surface Pro 7"
---

# How to install and configure Yazi on Hyprland

## Preface
Recently I came across [Yazi](https://github.com/sxyazi/yazi), which describes itself as a "blazing fast terminal file manager written in Rust, based on async I/O."

Since I am currently experimenting with [Hyprland](https://hypr.land/), I was looking for a terminal file manager.  

Yazi looked interesting, so I wrote down how I configured it to work with Kitty and how to use it as a file picker.

---

## Installing Yazi
According to the [Yazi Wiki](https://yazi-rs.github.io/docs/installation/), all you need to do is:

```bash
sudo pacman -S yazi ffmpeg 7zip jq poppler fd ripgrep fzf zoxide resvg imagemagick
```

---

## Configuring `hyprland.conf`
In your `hyprland.conf` there is a variable called `$fileManager`.
If we change it to simply call `yazi`, nothing happens because Hyprland does not know which terminal to launch it in.

Set it like this:

```ini
$fileManager = kitty -e yazi
```

Now, pressing your Hyprland file-manager shortcut (mine is `SUPER+E`) should open Yazi.

However, when quitting Yazi, Kitty may show an annoying warning:

> "Are you sure you want to close this OS window? It is running: yazi."

Let's disable that.

---

## Disable Kitty's window close warning
Edit your Kitty config:

```bash
nano ~/.config/kitty/kitty.conf
```

Find the setting `confirm_os_window_close`, uncomment it, and set it to:

```ini
confirm_os_window_close 0
```

---

## Configure Yazi openers
```bash
mkdir -p ~/.config/yazi
cd ~/.config/yazi
nano yazi.toml
```
Add:
```toml
[mgr]
show_hidden = true

[opener]
play = [
        { run = 'mpv "$@"', orphan = true }
]
edit = [
        { run = 'nano "$@"', block = true }
]
json = [
        # If you have VSCODIUM installed
        { run = 'vscodium --ozone-platform-hint=wayland "$@"', block = true }
]

[open]
prepend_rules = [
        { name = "*.json", use = "json" },
        { name = "*.jsonc", use = "json" },

        { mime = "text/*", use = "edit" },
        { mime = "video/*", use = "play" },

        # Multiple openers for a single rule
        { name = "*.html", use = [ "open", "edit" ] }
]
```

> **Info:** `prepend_rules` puts these rules in front of Yazi's defaults. Plain `rules` would replace the defaults entirely, and everything not listed here, like images or PDFs, would lose its opener.

---

## Set Yazi as the default file picker
This is somewhat of a rabbit hole. Some applications use the configured system FileChooser, while others implement their own, Firefox being a notable example.  

Even with a configured `~/.config/mimeapps.list` I could not get Firefox to use Yazi.  
The following setup worked for me.  

### Install xdg-desktop-portal-termfilechooser
```bash
yay -S xdg-desktop-portal-termfilechooser-hunkyburrito-git
```

#### Configure termfilechooser
```bash
mkdir -p ~/.config/xdg-desktop-portal-termfilechooser
cp /usr/share/xdg-desktop-portal-termfilechooser/yazi-wrapper.sh ~/.config/xdg-desktop-portal-termfilechooser/yazi-wrapper.sh
nano ~/.config/xdg-desktop-portal-termfilechooser/config
```

Paste this:
```ini
[filechooser]
cmd=yazi-wrapper.sh
env=TERMCMD=kitty
create_help_file=0
default_dir=$HOME
open_mode = suggested
save_mode = last
```

Restart the xdg desktop portal service:
```bash
systemctl --user restart xdg-desktop-portal.service
```

#### Configure xdg-desktop-portal 
We should also set our preferred FileChooser in `~/.config/xdg-desktop-portal/portals.conf`.
```bash
mkdir -p ~/.config/xdg-desktop-portal
nano ~/.config/xdg-desktop-portal/portals.conf
```

Add:
```ini
[preferred]
org.freedesktop.impl.portal.FileChooser=termfilechooser
```

### Configure Firefox
In the Firefox address bar type:
```text
about:config
```
Accept the warning and continue.  

At the top is a search bar. Type in:
```text
widget.use-xdg-desktop-portal.file-picker
```
Set the value to `1`.

---

## Let the file picker float!
If you want the file picker window to float, add the following rule to your `hyprland.conf`:
```ini
windowrule = float, center, size 800 600, class:kitty, title:termfilechooser
```

> **Warning:** This is the window rule syntax from before Hyprland 0.53, which changed how window rules are written.  
> On a newer version, check the [Hyprland wiki](https://wiki.hypr.land/) for the current syntax.

---

## That's it!  
Applications should now be able to use `Yazi` to select files.

**One more thing to keep in mind:**    
While testing this with Firefox downloads, I noticed one quirk.
If you press `Enter`, the file is not saved. Instead, the instruction file is saved. Press `O` to confirm the save.

Cheers.