Python 3 Youtube-DL Terminal Based Youtube Video Player Using mps-youtube Library in Command Line




  Wheel Status


  • Search and play audio/video from YouTube
  • Search tracks of albums by album title
  • Search and import YouTube playlists
  • Create and save local playlists
  • Download audio/video
  • Convert to mp3 & other formats (requires ffmpeg or avconv)
  • View video comments
  • Works with Python 3.x
  • Works with Windows, Linux and Mac OS X
  • Requires mplayer or mpv

This project is based on mps, a terminal based program to search, stream and download music. This implementation uses YouTube as a source of content and can play and download video as well as audio. The pafy library handles interfacing with YouTube.

FAQ / Troubleshooting common issues



A standard search is performed by entering / followed by search terms.

You can play all of the search results by giving 1- as input

Repeating song/songs can be done with song_number[loop], for example: 1[3] or 4-6[2]

Local Playlists

Search result items can easily be stored in local playlists.

YouTube Playlists

YouTube playlists can be searched and played or saved as local playlists.

A playlist search is performed by // followed by search term.


Content can be downloaded in various formats and resolutions.


A basic comments browser is available to view YouTube user comments.

Music Album Matching

An album title can be specified and mps-youtube will attempt to find matches for each track of the album, based on title and duration. Type help search for more info.


Search results can be customised to display additional fields and ordered by various criteria.

This configuration was set up using the following commands:

Type help config for help on configuration options



Note~/.local/bin should be in your PATH for --user installs.

Using pip:

To install the experimental development version and try the latest features:

Installing youtube-dl is highly recommended:

(youtube-dl version dowloaded directly from youtube-dl website can’t be used by mps-youtube. While the version in the repositories is usually outdated)

For mpris2 support, install the python bindings for dbus and gobject:


You can install mps-youtube directly from the official repositories:

Arch Linux

You can install mps-youtube directly from the official repositories:

macOS X

Install mpv (recommended player) with Homebrew:

Alternately, you can install mplayer with MacPorts:

Or with Homebrew:

Install mps-youtube using Homebrew:

Additional Windows installation notes

As an alternative to installing with pip, there is a standalone binary available. Go to Releases and download mpsyt-VERSION.exe under downloads for the latest release.

Install the python colorama module to get colors (optional):

Mpsyt requires a player to use as a backend, with either mpv or mplayer supported. Mpv is the recommended option.

Mpv can be downloaded from

Extract both mpv.exe and to the same folder as mpsyt.exe or to a folder in the system path.

Alternately, mplayer can be downloaded from

Extract the mplayer.exe file, saving it to the folder that mpsyt.exe resides in (usually C:\PythonXX\Scripts\) or to a folder in the system path.

Run via Docker container

Using Docker, run with:

Additional Docker notes

If you would like to locally build the container you can run the following steps

Check out this repo:

Enter the directory and run docker build:

Now run the container interactively with:

In order to have access to the local sound device (/dev/snd) the container needs to be privileged.


Upgrade pip installation:


mps-youtube is run on the command line using the command:

Enter h from within the program for help.


Leave a Reply