ytm-player 1.8.0

A full-featured YouTube Music TUI client for the terminal

ytm-player

A full-featured YouTube Music player for the terminal. Browse your library, search, queue tracks, and control playback — all from a TUI with vim-style keybindings. Runs on Linux, macOS, and Windows.

Available on PyPI, AUR, NixOS, and Gentoo — actively maintained with cross-platform support.

Features

• Vim-style keybindings — j/k movement, multi-key sequences (g s for search, g l for library), count prefixes (5j)
• Synced lyrics — live-highlighted with LRCLIB fallback for tracks YouTube doesn't have, with title sanitization for better LRCLIB matches
• mpv backend — gapless audio, stream prefetching, broad codec support
• Cross-platform native integrations — MPRIS (Linux), Now Playing (macOS), media keys (Windows)
• Theming — 18+ Textual themes plus per-app color overrides in theme.toml
• Spotify import — pull playlists in via API or scraper fallback
• CLI + IPC — control a running TUI from another terminal (ytm play, ytm pause, etc.)
• Free-tier support — works without YouTube Music Premium
• Session resume — last-playing track + queue restored on launch
• Local cache — LRU audio cache for offline-like replay of previously heard tracks
• Discord + Last.fm — Rich Presence and scrobbling

Requirements

• Python 3.10+
• mpv (audio playback backend, must be installed system-wide)
• A YouTube Music account (free or Premium)

Install

# PyPI (Linux / macOS / Windows)
pip install ytm-player

# Arch / CachyOS / Manjaro (AUR)
yay -S ytm-player-git

For NixOS, Gentoo, Windows-specific mpv DLL setup, source builds, and optional extras (Discord, Last.fm, Spotify import, etc.), see docs/installation.md.

Quickstart

ytm setup    # one-time auth (auto-detects browser cookies)
ytm          # launch the TUI

Windows: replace ytm with py -m ytm_player.

Documentation

Topic	Link
Per-platform install + optional extras	docs/installation.md
config.toml + theme.toml reference	docs/configuration.md
Full keyboard + mouse keybindings	docs/keybindings.md
All ytm CLI subcommands	docs/cli-reference.md
Spotify playlist import	docs/spotify-import.md
Troubleshooting (mpv / auth / MPRIS / macOS / cache)	docs/troubleshooting.md
File layout + stack	docs/architecture.md
Contributing	CONTRIBUTING.md
Security policy	SECURITY.md

Contributors

Thanks to @dmnmsc, @Villoh, @valkyrieglasc, @dsafxP, @Thayrov, @glywil, @Kineforce, @CarterSnich, @Tohbuu, @nitsujri, @uhs-robert, @moschi, and @firedev for bug reports, fixes, packaging, and platform support.

Changelog

See CHANGELOG.md for the full release history.