Skip to content


Dmitriy K edited this page Feb 21, 2020 · 19 revisions

Troubleshooting / FAQ

I see results, what's going on?

The codebase has now been updated to use v3 of the data API. Please ensure you're on the latest version of mps-youtube.

Search results not relevant or differ from YouTube website

By default mps-youtube is set to search for videos in the music category. To change this to all categories, enter:

set search_music false

from within mps-youtube.

Downloaded audio files won't play in iTunes / other player or can't be tagged

Install ffmpeg (or avconv), mps-youtube will use it to fix the container data for future downloads.

Not enough search results

Enter n and p to view the next/previous page of results

I can stream audio but can't see the video

By default mps-youtube is set to play audio only. To view video output, enter:

set show_video true

from within mps-youtube.

Can I use an external application for downloads?

Yes, use set download_command to specify a custom command to use for downloading.

Type help dl-command from within mps-youtube for more help

Note that using a custom download command does not support transcoding the downloaded file to another format using mps-youtube.

Custom mplayer or mpv keyboard shortcuts are ignored

If you have defined custom keymappings for mpv or mplayer in an input.conf file and wish to use them in mps-youtube, copy (or symlink) the config file to the mps-youtube config dir. The file must be named mpv-input.conf or mplayer-input.conf

The mps-youtube config dir can be determined by running mpsyt --version

Search ordering settings don't seem to apply to channel listings

Currently there's a separate setting (user_order) that can be used to specify the desired search order for user results (separate to general searches). Ensure this is set appropriately.

Future releases will have the user_order automatically inherit from the order setting.

How to install the development version?

WARNING: This is development version which is changed continuously. If you have some problems, try regular upgrade with sudo pip install mps-youtube --upgrade. If that's not working for you, then try installing development version.

sudo pip3 install --upgrade

NOTE: If you want to rollback to the stable release, just uninstall with sudo pip uninstall mps-youtube and then install again with sudo pip install mps-youtube.

Encoding errors while downloading videos with non-ASCII characters in title

If you try to download a video that has non-ASCII characters in its title and you get an error like the following:

Problem playing last item: 'ascii' codec can't encode character...

for some reason, Python is detecting your terminal as not capable of supporting UTF-8. As a workaround, run


before running mpsyt.

Youtube Error 403: The request cannot be completed because you have exceeded your quota.

mps-youtube shares a single youtube api_key for everbody, but as the user base grow larger, we may exceed the quota for a single api_key, if this happens, you can set your own api_key from the guide below (follow till step 3)

then set it in mps-youtube via

set api_key <key value>

and restart app.

If you can not even open the application, first delete cache with command: rm ~/.config/mps-youtube/cache_py_*

Clone this wiki locally
You can’t perform that action at this time.