youtube-tui: a terminal YouTube browser that launches other programs to do the work

The design decision is to launch other programs

Written in Rust, the YouTube TUI is a lightweight and user friendly TUI for browsing YouTube content from the terminal. It works out of the box and is easily configurable, and it supports Linux and Windows.

The key sentence about how it works is this: it is like an app launcher, it launches other programs to do the heavy lifting, for example `mpv` for playing videos. And then the honest footnote: it also has an embedded mpv music player, but that can be disabled in compile time.

This is the whole architecture in one paragraph, and it is a design choice with a specific consequence. A terminal application that wants to show YouTube thumbnails, let you search, filter results, manage subscriptions, and keep a watch history could implement all of that itself, downloading video, decoding audio, and rendering a player. This one does none of that. It is an interface over the commands you would otherwise type.

The project states this twice, in slightly different words. The YouTube TUI does not work on its own, it is instead like a TUI frontend for programs like `mpv` or `yt-dlp`/`youtube-dl`. However, the programs to launch can be changed, and therefore the YouTube TUI does not rely on any specific dependencies to run.

The dependency-free claim is in the summary with an asterisk, and the asterisk points at the installation documentation section on features. So the framing is: the TUI itself pulls in no external programs it cannot work around, but the things it launches are yours to choose, and the default choice is mpv, yt-dlp, and a browser.

The result is a program whose size and build complexity stay small, at the cost of being at the mercy of three external tools whose behaviour and output format it has to parse.

The config file is where the behaviour actually lives

The YouTube TUI can be customised through config files, located in `~/.config/youtube-tui` on Linux or `%APPDATA%\youtube-tui` on Windows, in the YAML format. The example in the project summary is the whole file:

mouse_support: true
max_watch_history: 50
allow_unicode: false
images: Sixels
refresh_after_modifying_search_filters: true
provider: YouTube
env:
  browser: xdg-open
  video-player: mpv
  youtube-downloader: yt-dlp
  terminal-emulator: konsole -e

The `env` block is the part that makes the app-launcher design real. Every external program the TUI invokes is named there, so the browser, the video player, the downloader, and the terminal emulator are all configurable, and swapping yt-dlp for youtube-dl or mpv for something else is a config change rather than a rebuild.

The rest of the keys cover the interface. `mouse_support` turns on mouse handling. `max_watch_history` bounds the stored history at 50 entries. `allow_unicode` is set to false here, which is a compatibility setting for terminals that cannot render the glyphs the interface wants. `images: Sixels` selects the image rendering path, and the alternative is the half-block mode. `refresh_after_modifying_search_filters` re-runs the query when a filter changes. And `provider: YouTube` selects the backend, which is a Cargo feature in its own right.

The summary says that anything from layouts to colours and keybindings can be customised, with more on that in the user manual, which is at tui.siri.ws/youtube and is where the installation guide and the rest of the documentation live.

One warning in the summary is worth repeating. Consider regenerating config files on updates to allow new features. That is a strong signal that the config format is still moving, and it means an upgrade can leave you with a file the new version does not fully understand.

What the interface actually does with YouTube

The project claims you can browse YouTube with almost all of its features and functions, and the list is specific enough to be useful.

You can view information about channels, playlists, and videos. You can use search filters to sort and filter search results. You can save browsing history. And there is an embedded audio and music player.

Then the additional features: vim-like commands, mouse support, an extensible keybindings system, an offline library, and subscriptions.

The vim-like commands and the extensible keybindings are what separate this from a simple wrapper. A terminal application that you drive with a mouse is a small step up from a web page, and one you drive with vim-like commands is a different kind of tool, and for people who live in a terminal that difference is the whole point. The offline library and subscriptions are the two features that turn a viewer into something you use daily, since they make the application a library you own rather than a window onto a website.

The screenshots in the summary show three views. The first is the main interface, the second shows the dependency picture, and the third shows another part of the interface.

The `provider` key in the config and the `invidious` Cargo feature point at the alternative backend. The feature list in the Cargo manifest includes `invidious = ["invidious/httpreq_sync"]`, and the `invidious` dependency itself is optional, with version 0.7 and no default features. So there is a second way to get the data, and the choice is a compile-time feature and a config value rather than a runtime switch, which is a reasonable trade since it avoids shipping both code paths.

The `rustypipe` feature, which takes no dependencies, is another entry in the same list, and the `mpv` feature maps to a dependency called `libmpv-sirno`, which is the embedded music player that can be compiled out.

The Cargo manifest tells you the rendering and platform story

The package metadata is where the technical details sit, and there are several that explain how the interface looks.

The crate is `youtube-tui` at version 0.9.5, edition 2021, licensed GPL-3.0-or-later, and categorised as command-line-interface and command-line-utilities. The documentation is on docs.rs and the homepage is the user manual site.

The default features are `sixel`, `halfblock`, `clipboard`, `mpv`, and `rustypipe`. The `sixel` feature enables `viuer/sixel`, which is the sixel image support in the viuer library, and `halfblock` enables viuer without it, so the two are the two image rendering strategies: a real sixel image, or the half-block technique that approximates an image using block characters in a terminal that has no sixel support. That is a real portability decision, and it explains why `allow_unicode` is a setting at all.

The `clipboard` feature pulls in the clipboard crate, `mpv` pulls in the embedded player, and `invidious` enables the alternative data provider.

The dependency list tells you the stack. `ratatui` at 0.30 with the serde feature is the terminal UI framework, and `crossterm` at 0.29 with the serde feature is the terminal handling and input layer underneath it. `tui-additions` at 0.4.3 with the framework and widgets features supplies the higher-level widgets. `viuer` at 0.11 with the print-file feature handles the image rendering. `serde` with derive, `serde_yaml_ng` for the YAML config, and `serde_json` for the API responses. `dirs` at 5 finds the config directory, `chrono` with the clock feature for timestamps, and `dyn-clone` for the object-safe cloning that a widget library tends to need.

There is one dependency that stands out and that the project itself flags. `typemap` at 0.3, with no default features, is listed as an urgent TODO item, marked as a no-longer-going-to-compile dependency to be replaced with either a self implementation or a usable crate. The comment underneath is blunt: this has been urgent for over 2 years now, maybe the deprecation warnings aren't real, nothing ever happens.

That is an unusually candid note to leave in a manifest, and it is the kind of detail that tells you what a project summary written by the maintainer would not tell you.

The packaging, the platform extras, and the rewrite that is coming

The repository root shows a project that ships in several forms and is preparing for a rewrite.

There is a `PKGBUILD` at the root, which is the Arch Linux packaging recipe, and there is a badge for the AUR, the Arch User Repository. There is a `Cargo.lock`, a `build.rs` for the build script, a `flake.nix` with a `flake.lock` for a Nix flake, and a `.envrc` for direnv. The `docs/` directory holds the source of the user manual, and there is a `setup-mpv-dev.ps1` PowerShell script for setting up a development version of mpv on Windows, plus a `threadcounter.sh`.

That mpv setup script is a good indicator of how the embedded player is developed. The `mpv` Cargo feature depends on `libmpv-sirno`, which links against libmpv, and building against a development build of mpv is how you get the library and its headers in place. So a contributor working on the embedded player needs a local mpv build, which is why there is a script for it and why the exclusion list in the manifest excludes the docs directory, the LICENSE, the threadcounter script, and the PKGBUILD from the published crate.

Then there is the item at the top of the project summary, which is commented out but still visible in the file. It reads: YouTube TUI is being rewritten, with a link to issue 48 to learn more.

That single commented-out line is the most important fact in the repository for anyone considering depending on it. The project is being rewritten, the existing implementation is the one you would use today, and the rewrite is tracked in an issue rather than a branch, so the migration path is not documented in the tree. The release history supports the picture of a project that ships regularly but slowly: v0.9.2 in September 2025, v0.9.3 in October 2025, and v0.9.4 in March 2026, with the manifest now at 0.9.5 and the last push on 2026-05-29.

The crates.io download badge, the AUR version badge, and the crates.io version badge in the header tell you all three distribution channels are live.

Where youtube-tui is the wrong tool

The limits here are more interesting than usual, because the project is candid about them.

First, the dependency on external programs is a feature and a liability. You need mpv, or whatever you substitute, yt-dlp, and a browser. The TUI parses the output of those tools, so a change in yt-dlp's output format is a change in whether the TUI works, and yt-dlp is a project that changes often. The dependency-free asterisk is accurate but narrow. The TUI has no hard dependency of its own on a particular program, and it has a hard dependency at runtime on a set of programs behaving as expected.

Second, the rewrite is in progress. If you adopt this today, you are adopting a version the author is replacing. The 0.9.x line will get maintenance, and the rewrite will get a new line, and the config format, the keybindings, and the features will all move. For a tool you use personally that is fine. For a tool you are about to build a workflow around, it is a schedule risk.

Third, the `typemap` situation is a genuine smell, not a detail. A dependency that the maintainer believes will not compile, marked urgent for over two years, with the note that nothing ever happens, is a signal about how this repository is maintained. It may well be fine, since the project clearly builds and ships releases, but the pattern of leaving a known-broken dependency in place is a pattern.

Fourth, the TODO list shows the scope of what is not done. A Git-like command line to improve on yt-dlp, so you can make changes to existing downloaded playlists instead of redownloading the whole thing. Channel caching and bookmarking. Selecting an item on the channel list moving focus to the feed items. These are the features a user would expect, and their absence tells you how far along the project is.

Fifth, and this is the platform one, the support is Linux and Windows. There is no macOS build mentioned in the summary, and the `env` configuration shows a `xdg-open` browser launcher and a `konsole -e` terminal emulator, which are both Linux-specific defaults. The Windows path is `%APPDATA%` and a PowerShell setup script, so the two platforms are supported through different configuration rather than one portable one.

Sixth, and it is the simplest objection: this is a browser for a video site whose frontend changes. Any terminal interface to a web service is coupled to that service's HTML or API, and YouTube's changes are not on the project's schedule. The `provider` abstraction and the `invidious` feature are the mitigation, since an alternative backend that is not YouTube itself is less likely to break under you, and that is a good reason to look at the Invidious option before committing to the YouTube provider.

Editorial conclusion

youtube-tui fits a terminal user who wants to browse and play YouTube without a browser, and who already has mpv and yt-dlp installed and is willing to configure a YAML file. It is the wrong tool if you need a GUI, a reliable download pipeline, or a project that promises a maintained dependency graph. Check three things before you install: that you have the external programs it launches, since it works on its own only as a frontend, that the configuration regenerates cleanly on upgrades, because the project asks you to consider regenerating config files to allow new features, and that you read the TODO list, because it names a dependency that no longer compiles and has been urgent for over two years.

Frequently asked questions

Official sources

1. License: GPL-3.0
2. Project website
3. README
4. Releases
5. Siriusmart/youtube-tui on GitHub