YTFZF – Search and play YouTube videos in the Terminal

Search YouTube Videos In The Terminal

We have already discussed playing YouTube videos with MPV, but that method lacked a search feature. Every time you had to play a video in MPV either you have to drag and drop the link on MPV or paste it in the Terminal, which in turn requires you to have the link in the first place. So you end up opening a web browser in the first place and thus end up defeating the entire point of not opening a web browser.

Through YTFZF, you can search and open the videos directly from your terminal. In this tutorial, I will guide you through the step-by-step process of installing this tool.

Also read: Customize MPV player for better usability

Install dependencies

If you are using any modern distribution, there is a high chance that you are using Wayland and not Xorg. Still, first, check what session you are using by typing the following commands in the Terminal :

Check The Session Type In Your Distribution
Check The Session Type In Your Distribution

This step is important as we will be installing dependencies for this application and certain packages are not supported on Wayland. Finally, install the following package by typing the commands depending upon your distribution if you have X11 :

# On Debian and Ubuntu based distributions :
sudo apt update && sudo apt install jq curl fzf ueberzug

# On Fedora Workstation
sudo dnf install jq curl fzf ueberzug

# On Arch Linux based distributions
sudo pacman -S jq curl fzf ueberzug

If you are on Wayland, I would recommend you to use the Kitty Terminal to avoid any hassle. Install all the dependencies by typing :

# On Debian and Ubuntu based distributions
sudo apt update && sudo apt install jq curl fzf kitty

# On Fedora Workstation
sudo dnf install jq curl fzf kitty

# On Arch based distributions 
sudo pacman -S jq curl fzf kitty
Installing The Dependencies
Installing The Dependencies

In this tutorial, I’m going to use kitty on X11, nonetheless because ueberzug was throwing out some error I couldn’t figure it out after searching for hours.

Install YTFZF

Finally, let’s get started with the installation of the actual package. Arch Linux-based users have an advantage here because the package is available in the AUR, and therefore they can easily update their package version. Install it from the AUR using your favourite AUR helpers such as yay or Paru :

# Yay users :
yay ytfzf

# Paru users :
paru ytfzf

For any other Linux Distribution users, you can directly install it by typing the following in the Terminal :

git clone
cd ytfzf
sudo make install doc

After the installation is complete, you can remove the previously created directory by typing the following command :

cd ~/
rm -rf ytfzf

Edit the config files

Create a config file for this application by

mkdir ~/.config/ytfzf/
cd ~/.config/ytfzf/

Now, with your favourite text editor, create a file by typing :

# For Vim users

# For Nano users
My Config File Looks Like This
My Config File Looks Like This

You can edit the parameters above. I’ve set up the video to play at 720p30fps. I have also disabled the history. By default, this CLI tool will play any media using the MPV player, so make sure that you add the video_player=vlc parameter.

Note that thumbnail_viewer=’kitty’ is an important parameter, otherwise, you can’t see the thumbnail previews of the YouTube videos.

You can also set up various other parameters by looking up the man page of the ytfzf command. Type in the Terminal :

man ytfzf
Manual Page Of Ytfzf
Manual Page Of Ytfzf

Playing videos

For the sake of simplicity, let’s create an alias for ourselves so that the launch process becomes a lot easier to use. Type the following in your terminal :

alias yt='ytfzf -t'
source .bashrc

Finally, open the Kitty Terminal and type the following to search for any media :

Searching Through YTZFZ
Searching videos Through YTZFZ in the Kitty Terminal

You can use the arrow keys to go up and down, and press enters to play any video. TO exit out of the menu, press Ctrl+c or Ctrl+q. You can also queue the videos by pressing the Tab key to select a number of videos, and then press enter to play them.


As long as you have SponsorBlock added with the mpv player, you can basically skip ads, sponsors and trackers by playing a video by this method. This method saves you a lot of system resources and thus you can open multiple tabs without any issue.


GitHub Page – YTFZF