ytfzf – Search (With Thumbnails) And Play YouTube Videos From A Terminal

ytfzf - search and play youtube with thumbnails from the command line

ytfzf is a script to search, download and play YouTube videos by making use of mpv and youtube-dl under the hood. It works on Linux and macOS. The command line script had its first stable (1.0.0) release today.

The tool initially started as a single line script, but has since evolved, recently gaining the ability to show YouTube thumbnails in the terminal, along with other enhancements. 

For each YouTube search query, a list of results in shown in the right-hand side pane. On the left-hand side you can see the selected video title, the channel that posted the video, the number of views, video duration, upload date, and the video thumbnail (which is optional). 

Use the Up and Down arrow keys to navigate through the search results, and press the Enter key to play the video (or download it, it ytfzf was started with the -d command line parameter). The videos are played using mpv by default, but you can change this with another video player, as long as it has the ability to launch YouTube links.

The thumbnails are implemented using Überzug, a command line utility which allows drawing images on terminals by using child windows. Since Überzug only works on X11, the ytfzf video thumbnails feature is also tied to X11 sessions, and does not work on Wayland. Also, don’t expect this to work in a tty – it won’t.

It’s worth noting that the video thumbnails may sometimes be displayed outside the terminal window. In such cases you’ll need to resize the terminal, then press the Up / Down arrow keys to select a different video, and it will use an updated thumbnail size.

Besides this, ytfzf also features support for video history, allows choosing the media format, and can queue multiple tracks (using fzf multi-selection). You can search for YouTube videos and play / download using fzf, dmenu or rofi.

Other features include the ability to play / download audio only, auto-play and repeat YouTube videos, play a random search result, and there’s also an option to show available media formats before proceeding.

See the ytfzf --help for a complete list of options.

For future releases, the developer intends to implement support for YouTube playlists and comments. There’s no timeline for when these features will be implemented though.

Related: How To Download A YouTube Playlist And Convert It To MP3 Using youtube-dl (Command Line)

Configuring and using ytfzf

The ytfzf configuration can be set in the ~/.config/ytfzf/ file, or using environment variables. Let’s use ~/.config/ytfzf/ to set everything up below. Create the ~/.config/ytfzf folder:

mkdir ~/.config/ytfzf

Now open ~/.config/ytfzf/ in a text editor (create it since it doesn’t already exist), and paste the following:

YTFZF_HIST=1 # history is on by default it can be set to -> 0 history off, 1: history on
YTFZF_LOOP=0 # if set to 1 it is on but normally it is off by default. Can be turned on using option -l
YTFZF_PREF="bestvideo[height<=?1080]+bestaudio/best" # set the
video format
YTFZF_ENABLE_FZF_DEFAULT_OPTS=1 # fzf colors are going to be the one from your fzf configuration
FZF_PLAYER="mpv" # sets the video player used by ytfzf (mpv by default), e.g. FZF_PLAYER="devour mpv"; you can also specify the YTFZF_PLAYER_FORMAT, e.g. YTFZF_PLAYER_FORMAT="devour mpv --ytdl-format="

This is an example configuration. You can change some of these settings, use them as they are, or uncomment them to use the defaults. You can find more configuration options here.

Using ytfzf is as easy as running:


After typing this command, you’ll be prompted to enter the YouTube search query, like this:

$ ytfzf

Search Youtube:

You can specify the search query directly, so ytfzf doesn’t prompt you for a query, like this:

ytfzf <query>

The YouTube search results won’t have thumbnails while using this though. To enable thumbnails, run ytfzf with the -t (or --thumbnails) command line parameter:

ytfzf -t

By default, ytfzf plays a video from your search results when you hit Enter. If you want to download the video instead of playing it, use the -d command line parameter:

ytfzf -d

Want to queue YouTube videos in ytfzf (and thus, in mpv)? Press Tab to select each video that’s going to be added to the queue, to be played in mpv. Use > and < (so use Shift + > and Shift + <) to navigate through the queue to the next and previous videos.

For more details on configuring and using ytfzf, including how to use it with external menus such as dmenu or rofi, see its project page.

Install ytfzf

ytfzf can be installed from AUR on Arch Linux / Manjaro, and using the nitratesky overlay on Gentoo. You may also install it on macOS. The tool might also work on Windows, using WSL, but I didn’t try it.

For other Linux distributions, installing ytfzf is fairly easy since it’s just a script. You’ll need to install its dependencies manually though: mpv, youtube-dl, fzf (optional, for menu), jq and ueberzug (optional, for video thumbnails; this too has some dependencies). We’ll also need git to get the latest ytfzf.

Below you’ll find step-by-step instructions for installing ytfzf on Debian / Ubuntu / Linux Mint / Pop!_OS and other Linux distributions based on Debian or Ubuntu, as well as for Fedora. You can install ytfzf on any other Linux distribution as explained below, but you’ll need to figure out the dependency names for your Linux distribution yourself.

As a reminder, video thumbnails don’t work on Wayland, so if you use Fedora or Ubuntu 21.04, which use Wayland by default, you can either use this without thumbnails, or switch from Wayland to the X11 session from the login screen.

1. Install the ytfzf dependencies, as well as the Üeberzug dependencies.

  • Debian / Ubuntu / Linux Mint / Pop!_OS:
sudo apt install jq mpv fzf git python3-pip python3-wheel python3-dev python3-xlib libx11-dev libxext-dev make

sudo dnf install$(rpm -E %fedora).noarch.rpm$(rpm -E %fedora).noarch.rpm

sudo dnf install jq mpv fzf git python3-pip python3-wheel python3-devel python3-xlib libX11-devel libXext-devel make

For any Linux distribution: Since youtube-dl is usually updated in the repositories (at least on Debian / Ubuntu), let’s install it from PyPi. We’ll also need to install ueberzu in the same way:

python3 -m pip install --user youtube-dl ueberzug

It’s probably a good idea to remove the youtube-dl package if you’ve installed it from the repositories. You can later update youtube-dl using python3 -m pip install --user --upgrade youtube-dl

2. Get the ytfzf GitHub repository, and install ytfzf:

git clone

cd ytfzf

sudo make install

This installs the ytfzf script into /usr/local/bin, so make sure you have this directory in your PATH.

In case you later want to uninstall it, navigate to the ytfzf directory and run:

sudo make uninstall

via r/unixporn