yewtube: a terminal YouTube player that skips the API key

What yewtube solves, and for whom

The project describes itself as a terminal based YouTube player and downloader, forked from mps-youtube, and its headline claim is that no YouTube API key is required. That single sentence defines the audience. Anyone who has tried to build a small script around the official YouTube Data API has hit the same wall: a Google Cloud project, an OAuth or API key, quota accounting, and a review process if the app is going to be used by other people. yewtube routes around that by treating YouTube as a web page to be scraped and a stream to be pulled, not as an API to be authenticated against.

The people who get value from this are narrow and identifiable. They are comfortable typing `/` to search and `1-` to play everything in a result list. They already have mpv, mplayer or VLC on the machine, since the README lists those as requirements. They want local playlists, album matching by title and duration, comment browsing and format conversion without leaving the shell. The README also notes that yewtube can run audio in VLC with no GUI, which is the clearest statement of intent in the whole document: this is a tool for machines without a desktop session, or for users who have one and prefer not to use it.

The mechanism: pafy, yt-dlp and an external player

The architecture is inherited almost entirely from mps-youtube. The README states that the pafy library handles interfacing with YouTube, and the dependency list in requirements.txt pins yt-dlp at version 2023.9.24 or newer, alongside yewtube-search-python, httpx, requests, pylast and pyperclip. So there are two layers doing the network work: a search layer and a download/stream extraction layer. That split matters when something breaks, because a change on YouTube's side can break one without the other.

Playback is not handled internally. The README lists mplayer, mpv or VLC as requirements, which means yewtube resolves a stream URL and hands it to a separate process. The mpv integration is the most interesting part of this design. If mpv is the configured player, you can soft-link mpv's own input bindings into yewtube's config directory, and yewtube will use them with a few usability changes of its own. That is a deliberate choice to delegate keybindings rather than reimplement them, and it means your existing mpv muscle memory largely carries over.

Configuration lives in a directory the program reports as Config dir, shown in the README's version output as /home/user/.config/mps-youtube. The directory name is a leftover from the parent project and is worth noting, because anyone migrating from mps-youtube will find their old config in the same place. Settings are changed at runtime with commands rather than by editing files: the README's customisation example uses `set order views` and `set columns user:14 date comments rating likes dislikes category:9 views`, and points to `help config` for the full list.

Installing yewtube and running a first search

The README gives two installation routes and explicitly recommends pipx over plain pip. The pipx route isolates yewtube in its own virtual environment and puts the `yt` command on your PATH.

pip install pipx
pipx install yewtube
yt

After the third command you should be inside the interactive prompt. Note that the executable is `yt`, not `yewtube`; setup.py registers the console script as `yt = mps_youtube:main.main`, so the package name and the command name deliberately differ.

If you want the code from the repository rather than the released package, the README documents a git-based install. This is the route to take if you need a fix that has landed on master but is not in a release yet.

pipx install git+https://github.com/mps-youtube/yewtube.git
yt

Inside the program, a search is a slash followed by your terms, and a playlist search is a double slash. The README's examples: `/` plus search terms performs a standard search, and `//` plus a search term performs a playlist search. Entering `1-` plays every result in the list. Looping uses bracket notation, so `1[3]` repeats the first result three times and `4-6[2]` repeats results four through six twice. Pressing `h` brings up help.

Before any of that works, the player has to exist on the system. If playback fails silently, the missing dependency is the first thing to check, because yewtube does not bundle a player and the README treats mplayer, mpv or VLC as prerequisites rather than optional extras.

Upgrading, and why the dependency line matters more here

The upgrade instructions are split by install method, which is a small but useful signal that the maintainers expect both to be in use. For pipx installs the README gives `pipx upgrade yewtube`, and for pip installs `pip install --upgrade yewtube`. Both have an optional variant that also pulls dependencies forward, using `--upgrade-strategy eager`.

That eager flag is worth understanding rather than copying blindly. yewtube sits on top of yt-dlp, and yt-dlp is the component that has to keep pace with YouTube's delivery changes. A yewtube release that does not bump yt-dlp can still work if your installed yt-dlp is recent enough. The README's own version output shows this explicitly: it prints both the yewtube version and the yt_dlp version as separate lines. When something stops playing, that second line is the first diagnostic you have, and the eager upgrade is the documented way to move it.

The project's release history shows the cost of this arrangement. v2.13.1 landed on 2026-03-04, while v2.12.0 and v2.11.7 both landed on 2024-09-11. The last push to the repository was on 2026-03-04. There is a gap of roughly eighteen months between the 2.12 line and 2.13.1, and during that gap the only thing standing between users and a broken player was whether yt-dlp had shipped a fix. That is not a criticism of the maintainers so much as a structural property of any scraper-based client: your uptime is partly someone else's release schedule.

Where yewtube is the wrong tool

The most concrete limitation is visible in the repository itself. The Dockerfile at the top level is not a yewtube image. It is labelled for mps-youtube, points its vcs-url at the mps-youtube repository, and its build steps run `pip install --no-cache mps-youtube youtube-dl`. It also sets the entrypoint to `mpsyt`, not `yt`. Anyone who finds that file and assumes it builds yewtube will get the parent project, an older download backend, and a different command name. The README does not document a container workflow at all, so container users are effectively on their own.

The second limitation is the player dependency. yewtube is a front end; it does not decode audio or render video. On a headless server with no mpv, mplayer or VLC, the program can search and download but cannot play, and the README's prerequisites make that clear without offering a fallback. If your goal is a self-hosted web interface with a browser player, this is not it.

The third is the nature of the YouTube interface. Because the project relies on scraping rather than an authenticated API, it inherits all the fragility that comes with that. The README does not document rollback, a compatibility matrix, or a supported-versions policy for yt-dlp. When playback breaks, the documented remedies are the upgrade commands and the wiki's troubleshooting pages, not a pinned working combination. For a personal tool that is acceptable. For anything you would put in front of other people, it is a real operational risk.

Alternatives: Invidious and yt-dlp on their own

The obvious comparison is Invidious. The two solve overlapping problems from opposite directions. yewtube is a local client: it runs on your machine, keeps your playlists in a config directory, and depends on an external media player. Invidious is a server-side proxy that presents YouTube through a web interface, so the browser is the client and someone has to host or choose an instance. If you want to watch in a browser and share a link, Invidious is the closer fit. If you want a keyboard-driven shell tool that hands streams to mpv, yewtube is.

The second alternative is using yt-dlp directly. yewtube's download and extraction path already goes through yt-dlp, so a user who only wants to fetch files is adding an interactive layer they may not need. What yewtube adds on top is the search interface, the result list with configurable columns, local playlists, album matching by title and duration, and the comment browser. Those are the reasons to use it. If you strip them away, you are left with a wrapper around a tool you could call yourself, and the wrapper is the part that needs the external player.

Licence and the cost of keeping it running

yewtube is GPL-3.0. That is a copyleft licence. For an end user running `yt` on a laptop, the practical effect is nil. For anyone embedding yewtube in a larger product, the obligation to release corresponding source for derivative works is the thing to understand before writing code against it. This is a description of the licence, not legal advice; if you are shipping something, have someone qualified read the LICENSE file.

Maintenance cost has two parts. The first is the upgrade cadence: `pipx upgrade yewtube` or `pip install --upgrade yewtube`, plus the eager variants when the download backend needs to move. The second is the config directory at ~/.config/mps-youtube, which persists across upgrades and carries the mps-youtube name. Nothing in the README suggests that directory is going to be renamed, so plan for it to stay where it is. The mpris extra, which exposes yewtube to desktop media controls, adds its own dependency chain: dbus-python and PyGObject, with the README pointing at the PyGObject installation guide for the platform-specific parts. That extra is only worth installing if you actually want media key integration, and the README's own verification step is to run `playerctl -l` and look for an entry beginning with mps-youtube.

Editorial conclusion

Adopt yewtube if you already live in a terminal, have mpv, mplayer or VLC installed, and want search, local playlists and downloads without registering a Google API key. Skip it if you need a graphical interface, an officially maintained container image (the Dockerfile in the repository still installs mps-youtube and youtube-dl), or a player whose YouTube-facing layer the project itself controls. Before committing, run yt --version and confirm the yt_dlp version it reports, because that line tells you which download backend you are actually getting.

Frequently asked questions

Official sources

1. Issues
2. License: GPL-3.0
3. mps-youtube/yewtube on GitHub
4. README
5. Releases