TubeAmp needs two system libraries — libmpv, which it loads through ctypes to play audio, and ffmpeg, which decodes tracks for the spectrum analysis — plus Python 3.11 or newer. yt-dlp is a Python dependency and comes with the package, so it does not need installing system-wide.

# Arch Linux — the mpv package ships libmpv
sudo pacman -S mpv ffmpeg

# Fedora
sudo dnf install mpv mpv-libs ffmpeg

# openSUSE
sudo zypper install mpv libmpv2 ffmpeg

Then uv tool install tubeamp, or pipx install tubeamp. Both keep TubeAmp in its own environment rather than mixed into your system Python. Don't have either?

curl -LsSf https://astral.sh/uv/install.sh | sh   # uv
sudo apt install pipx                             # or pipx, from your package manager

If tubeamp comes back as "command not found", the install directory is not on your PATH yet. Both tools install into ~/.local/bin; uv tool update-shell (or pipx ensurepath) adds it, and the change takes effect in a new terminal.

Without the libmpv runtime package TubeAmp refuses to start and names the package to install for your system, rather than failing at first playback.

Not supported natively: python-mpv loads libmpv-2.dll through ctypes, and the official mpv build for Windows does not ship that library. TubeAmp runs under WSL2 instead, where the Linux instructions apply unchanged and WSLg handles audio — but setting WSL2 up is its own detour, and it needs a reboot:

wsl --install          # in PowerShell as administrator, then reboot

After the reboot, in the Ubuntu shell:

curl -fsSL https://raw.githubusercontent.com/tomekceszke/tubeamp/main/install.sh | bash
tubeamp

The one-liner at the top runs install.sh, which is short enough to read in a minute and does four things: finds a Python 3.11+, installs libmpv and ffmpeg through your own package manager, puts TubeAmp in its own virtualenv under ~/.local/share/tubeamp, and links it into ~/.local/bin.

It shows every command before running it and asks first — including the ones needing sudo, and before it touches your shell's startup file. It never installs Homebrew for you; on macOS without it, it stops and points you at brew.sh.

Reading it before running it is sensible:

curl -fsSL https://raw.githubusercontent.com/tomekceszke/tubeamp/main/install.sh -o install.sh
less install.sh && bash install.sh

bash install.sh --dry-run     # print the whole plan, change nothing
bash install.sh --yes         # no questions, for scripts and the impatient
bash install.sh --uninstall   # remove it again, leaving ~/.config/tubeamp alone

Re-running it upgrades an existing install.

If playback stops working after a while, YouTube has most likely moved on from the pinned yt-dlp. Upgrading is the fix:

brew upgrade tubeamp          # Homebrew
uv tool upgrade tubeamp       # uv
bash install.sh               # the install script, re-run

Nothing here is a binary you have to trust on faith. Every release is built from a tagged commit by a GitHub Actions workflow and published to PyPI through Trusted Publishing, so no token is stored anywhere and each file carries an attestation linking it back to the commit and the workflow run that produced it. The Homebrew formula lives in tomekceszke/homebrew-tap and builds from that same published source.

git clone https://github.com/tomekceszke/tubeamp.git
cd tubeamp
./install.sh
./run.sh

It is the same install.sh, and it notices the difference: run from a checkout it installs the working tree in editable mode into .venv instead of fetching a release, so your edits take effect without reinstalling. run.sh rebuilds that virtualenv if a Python upgrade has left its interpreter symlinks dangling.