yewtube: A Terminal YouTube Player and Downloader Without an API Key

What yewtube Does and Why the No-API-Key Approach Matters

yewtube provides a full-screen terminal menu for searching YouTube, playing audio or video through an external player, browsing comments, managing local playlists, and downloading content in various formats. The original mps-youtube project required a YouTube Data API key, which must be registered through Google's developer console and is subject to daily quota limits. yewtube removes that requirement entirely, which is the first feature the README lists under 'What's new in yewtube?'.

The no-API-key approach matters because API key management adds a setup step that many users skip or encounter problems with. It also means the tool is not subject to quota throttling when a user does many searches in a session.

The README credits the lineage clearly: yewtube is a fork of mps-youtube, which is itself based on mps, a terminal music search and streaming tool. The pafy library handles the YouTube interface layer, and yt-dlp handles download operations. yewtube runs on Windows, Linux, and macOS, and requires Python 3.x.

To play audio or video, an external media player must be installed. The supported players are mplayer, mpv, and VLC. The README notes that running audio in VLC with no GUI is a specific feature of yewtube versus its upstream.

Search, Playlist Management, and Download Capabilities

Inside the terminal interface (launched with the yt command), a search is performed by entering / followed by search terms. To play all results, the input 1- sends every result to the player in sequence. Individual results accept repeat loops: entering 1[3] plays the first result three times, and 4-6[2] plays results four through six twice each.

YouTube playlists are searched with // followed by a term. Results can be saved as local playlists, which are stored by yewtube independently of YouTube. Music album matching is available: entering an album title causes yewtube to attempt to find YouTube matches for each track based on title and duration. The help search command (typed within the interface) documents the album search syntax.

Downloads support multiple formats and resolutions. Converting to MP3 and other audio formats requires ffmpeg or avconv to be installed on the system. The download workflow stays within the terminal interface rather than launching a separate graphical file picker.

Search results can be customised to show additional metadata fields. The README gives this configuration example:

set order views
set columns user:14 date comments rating likes dislikes category:9 views

Typing help config from within the program lists all available configuration options.

Installing yewtube and Running Your First Search

The recommended install method is pipx, which installs the package in an isolated environment and avoids conflicts with other Python packages:

pip install pipx
pipx install yewtube

After installation, the command to launch the interface is yt. For the stable release, a direct pip install also works:

pip install yewtube

To install the latest development version from the master branch:

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

To upgrade a pipx installation:

pipx upgrade yewtube

The setup.py requires Python 3.6 or higher. The runtime dependencies listed in requirements.txt include httpx (pinned below 0.28), yt-dlp at version 2023.9.24 or higher, yewtube-search-python at 1.6.7 or higher, requests, and pylast for Last.fm integration. On Windows, pyreadline3 and colorama are added automatically.

Connecting mpv Input Bindings and mpris Media Control

Users who prefer mpv as the playback engine can re-use their existing mpv keyboard bindings inside yewtube by creating a symbolic link:

ln -sr ~/.config/mpv/input.conf ~/.config/mps-youtube/mpv-input.conf

This soft-links the existing mpv input configuration into the directory yewtube reads for player settings, so custom mpv keybindings carry over into yewtube sessions without having to duplicate the configuration.

For desktop media control through mpris, yewtube requires PyGObject and GTK as additional dependencies. The install command for the mpris extra is:

pipx install 'yewtube[mpris]'

After installing, run `set mpris true` inside the yewtube interface to enable mpris. The playerctl command will then list the yewtube instance as a controllable media player:

playerctl -l

The README shows that a working mpris setup will list the instance as mps-youtube.instance followed by a number, since the underlying package name retained the original mps-youtube identifier. The version command confirms the yt_dlp version, Python version, platform details, encoding settings, and dbus connectivity when verifying that mpris is working:

yt --version

Configuration files are stored under ~/.config/mps-youtube/. The README directs users with problems to the yewtube wiki's common-issues page for troubleshooting specific errors. The pyproject.toml lists the mpris extra as requiring dbus-python at version 1.2.18 or higher and PyGObject at version 3.42.0 or higher, so both must be satisfied before mpris controls become available.

Where yewtube Falls Short

yewtube depends on the pafy library and yt-dlp to extract video URLs and metadata from YouTube. YouTube's backend changes frequently, and yt-dlp releases updates to track those changes. A version of yewtube that ships with a pinned yt-dlp dependency may break when YouTube changes its response format, requiring a yt-dlp upgrade independent of yewtube's own release cycle. The requirements.txt pins yt-dlp at 2023.9.24 or higher without an upper bound, which means upgrading yt-dlp to address a YouTube change could introduce incompatibilities yewtube's tests did not cover.

The Dockerfile in the repository installs mps-youtube and youtube-dl rather than yewtube and yt-dlp, which indicates the Docker image was not updated to reflect the fork's changes. Teams trying to run yewtube in a container should not use the repository's Dockerfile as a starting point.

MP3 conversion requires ffmpeg or avconv installed separately on the host. There is no bundled audio conversion; the README states this as a prerequisite without providing installation guidance.

The tool has no graphical interface and no web UI. Users who need queue management across multiple devices or playlist synchronisation with a server-side store will find yewtube's local-file playlist model insufficient.

How yewtube Compares to yt-dlp and Maintenance Status

yt-dlp is a command-line YouTube downloader that yewtube uses internally as its download backend. yt-dlp's approach is task-specific: you pass a URL and flags to download a file, with extensive format and quality options. It has no interactive search interface. yewtube wraps yt-dlp with a search menu, queue management, repeat controls, and playlist features, targeting users who want to browse and play YouTube from the terminal interactively rather than downloading files by URL.

The last push to the repository was on 2026-03-04, which is more than six months before the time of this writing. v2.13.1 was released on that same date. There have been no commits or releases after that point, and the maintenance status of the project is unclear.

The project is licensed under GPL-3.0. This is a copyleft licence: any distributed derivative work must be released under the same licence. The entry_points defined in setup.py register the yt command as a console script under the name yt = mps_youtube:main.main, and the package directory is mps_youtube, reflecting the original mps-youtube codebase that yewtube forked from.

Editorial conclusion

Developers and power users who want to search and play YouTube audio or video from a terminal without registering for a YouTube Data API key will find yewtube fits that need. Before relying on it for regular use, note that the last push to the repository was on 2026-03-04 and no commits have followed since: anyone who encounters a breakage from YouTube-side changes in the intervening months should check the issue tracker before assuming the tool is functional. Python 3.6 or higher is required, and an external player such as mpv or VLC must be installed separately.

Frequently asked questions

Official sources

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