Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time

Maintainer: Euro20179 Discord Discord

A POSIX script that helps you find Youtube videos (without API) and opens/downloads them using mpv/youtube-dl

This is a little showcase

Table Of Contents


There are only 2 required dependencies, however the rest require some configuration before you can replace them.

Required dependencies

Recommended dependencies

  • mpv (the default video and audio player)
  • fzf (the default menu selection screen)

Optional dependencies

  • yt-dlp (for downloading)
  • dmenu (only if using the -D option)
  • ueberzugpp
    • needed for the following thumbnail viewers:
      • kitty, iterm2, sixel, and ueberzug
    • the original ueberzug or any fork may be used if you only want to use the ueberzug viewer.

Thumbnail Viewers

  • To use a thumbnail viewer include -T <viewer> in the command when running ytfzf
Program Wayland Support
kitty (requires ueberzugpp)
iterm2 (requires ueberzugpp)
sixel (requires ueberzugpp)
swayimg only on sway
swayimg (-T swayimg-hyprland) only on hyprland


Repo status

if on linux and installed using make on version 2.0 or prior, run sudo make uninstall-old first

  1. Install the dependencies listed above
  2. Run the following commands
git clone
cd ytfzf
sudo make install doc
  • If you wish to not install documentation (highly unrecommended) run sudo make install instead.

  • If you wish to install addons, run sudo make addons

    • YTFZF_SYSTEM_ADDONS_DIR will point to /usr/local/share/ytfzf/addons even if you set PREFIX to something else
    • If you use a different prefix, it would be smart to export YTFZF_SYSTEM_ADDONS_DIR to $PREFIX/share/ytfzf/addons in a shell startup file.
  • You may also install ytfzf through your package manager, as listed on the side.


Addons are extra features that will not be as supported as everything built into ytfzf itself.

Addons are located in addons, copy any addon to ~/.config/ytfzf/{addon-type}/{addon}, and give it execute permissions.

You may also just copy the entire addon folder type, eg: cp -r addons/thumbnail-viewers ~/.config/ytfzf/


To use a scraper addon run ytfzf -c <scraper> ...

To use a thumbnail-viewer addon run ytfzf -T <viewer> ...

To use a interface addon run ytfzf -i <interface> ...

To use a url-handler addon run ytfzf -u <handler> ...

To use a sort-name addon run ytfzf --sort-name=<sort-name> ...

To use an extension addon run ytfzf -e <extension> ...


  • Subscriptions
  • Thumbnails
  • Watch history
  • Search History
  • Downloading
  • Queueing multiple videos
  • Custom menus, and scrapers
  • Addon support


Search with thumbnails

ytfzf -t <search>

Use dmenu as the menu instead of fzf

ytfzf -D <search>

Print the link of the selected video instead of playing it

ytfzf -L <search>

Search Odysee instead of youtube

ytfzf -cO <search>

Use the chafa thumbnail viewer, pass --vo=sixel, and --quiet to mpv, scrape odysee with the search odysee search, youtube with the search: youtube search, and also scrape subscriptions

ytfzf -t -T chafa --url-handler-opts='--vo=sixel --quiet' -cO,Y,SI --multi-search odysee search,youtube search


Everything that is an option can also be configured in ~/.config/ytfzf/

In addition, the video player and other things may be changed here

Here is a sample configuration (please dont use it)

For more information, see ytfzf(5) which should be installed, if it's not see the wiki.


  • dwm with swallow patch: Images don't render with ueberzug when looped (ie, option -l)
  • if thumbnails are not working .Xauthority might be causing it. Try deleting it and relogging into your computer.


Feel free to contribute, and add your name to the credits, please use the development branch. For more information see contributing


User Contributions Donate
Pystardust contributions
Euro20179 contributions
Simonhughxyz contributions
Jac-Zac contributions
Mudskipper875 contributions
Gardockt contributions
qoheniac contributions
mathisto contributions