Search, download and play music from YouTube.
Go to file
ProfP303 d37e993c38 Updated
- updated "AppImage Installation" for Debian and openSUSE
- fixed some typos
2023-07-05 16:41:42 +00:00
img Added qt-port of the GUI mode 2023-05-26 14:43:50 +02:00
scripts Updated AppImage-make-scripts to Python3.11 2023-07-05 17:35:20 +02:00
.gitignore Added dir __pycache__ to .gitignore 2023-06-05 10:16:06 +02:00 Refactoring 2023-07-03 23:00:02 +02:00 Updated 2023-07-05 16:41:42 +00:00
org.codeberg.ralfhersel.youplay.metainfo.xml Merged changes of version 0.46 from main branch 2023-07-03 10:08:15 +02:00
org.codeberg.ralfhersel.youplay.yml Merged changes of version 0.46 from main branch 2023-07-03 10:08:15 +02:00
requirements.txt Updated AppImage-make-scripts to Python3.11 2023-07-05 17:35:20 +02:00
requirements_pyqt6.txt Refactoring Qt/PyQt6 requirements 2023-07-03 21:40:39 +02:00
requirements_qt.txt Updated AppImage-make-scripts to Python3.11 2023-07-05 17:35:20 +02:00
youplay.desktop Desktop-file: set gtk4 as standard GUI 2023-06-08 22:00:27 +02:00
youplay.desktop.flatpak v0.44 2023-04-27 23:38:01 +02:00
youplay.desktop.python v0.44 2023-04-27 23:38:01 +02:00 Manually fix failed git-merge 2023-07-03 23:31:39 +02:00 Modified to launch with option --gui=gtk4 2023-07-03 19:42:28 +02:00
youplay.svg v0.19 2020-12-17 17:34:41 +01:00 Added current-dir on pathes for loading images. 2023-06-08 15:23:28 +02:00 GTK4-module: Reapplied button margins on play/quit 2023-07-05 17:54:53 +02:00 Refactoring before merging to main 2023-07-03 19:11:03 +02:00 Refactoring before merging to main 2023-07-03 19:11:03 +02:00

Logo Welcome to YouPlay

Do you love music, but hate restrictions?

With YouPlay you can search for whatever music in your mind. It will list a number of matching songs from YouTube. You can listen to it and YouPlay will download it as an mp3 file.

YouPlay in GUI-mode

YouPlay Screenshot GUI

YouPlay in CLI-mode

YouPlay Screenshot CLI


You can install the Python-Script, generate a Flatpak or try the AppImage:

  • I recommend to install YouPlay manually as described in the next chapter.

  • A Flatpak package is ready, but not distributed to because I don't want to feed Microsofts GitHub, which is required for publications. All files for the Flatpak are available in this repository, but you need to know how to build a Flatpak.

  • J.r maintains an AUR package

  • @ProfP303 created AppImages for various versions: check the AppImage files

Manual Installation

This installation method is still the preferred one, because it is easy and has the smallest installation size. Run these commands in a terminal:

git clone
cd youplay

Then install these packages with the package manager of your GNU/Linux distribution:

    mpv, libmpv1, ffmpeg, python3-pip
  • On Debian-based systems you can do this with following command:

      sudo apt install mpv libmpv1 ffmpeg python3-pip
  • On Arch-based systems:

      sudo pacman -S mpv ffmpeg python-pip
  • On Fedora-based systems:

      sudo dnf install mpv mpv-libs ffmpeg pip3
  • On openSUSE-based systems:

      sudo zypper install mpv libmpv1 ffmpeg libadwaita-1-0 yt-dlp python3-pympv

Now install the necessary Python libraries with:

    pip install -r requirements.txt

Note: If you are on a Qt-based desktop you might want to use the Qt-version instead (this will install the official "Qt for Python" aka PySide6-bindings by the Qt Company). For this see following chapter "Qt-port Installation"

Last steps:

  • Make and executable in your file manager

  • Change the paths (Exec and Icon) in youplay.desktop to your paths (e.g.: /home/yourpath/youplay). Please replace the Exec and Icon settings with absolute paths to your YouPlay directory. Example:

      Exec=/home/ralf/dev/youplay/ -g
  • Copy youplay.desktop to /home/user/.local/share/applications

Test it:

  • GNOME and KDE-Plasma: SUPER + youplay

  • Terminal: navigate to /home/user/[your_script_folder]/youplay/

    Run it with: ./

    If you get GUI or TUI depends on the settings in

Note: Alternatively you could use the full-automated online-installer from the shell (only wget has to be installed):

bash <(wget -O -

If installed via online-installer, you can uninstall YouPlay with following command: youplay-uninstall

AppImage Installation

Thanks to @ProfP303, there is an AppImage available. This image works on several desktop environments (Plasma, GNOME, LXQt, Cinnamon, MATE) if GTK4 and Libadwaita are available. Here are commands to install them:

  • Arch Plasma: sudo pacman -S gtk4 libadwaita

  • Fedora Plasma: sudo dnf install gtk4 libadwaita

  • Debian 12 ("Bookworm") Plasma: sudo apt install libgtk-4-dev libadwaita-1-dev

  • openSUSE Leap Plasma: sudo zypper install gtk4-devel libadwaita-devel

You can download an AppImage from the Releases-page, make it executable and run it. If you need a better integration in the GNOME-Desktop, take a look at AppImageLauncher. Install it before you launch the AppImage with AppImageLauncher.

Here you can find also an older AppImage, which is based on GTK3, in case your distribution does not support GTK4 and Libadwaita. The features are almost the same.

Qt-port Installation

The Qt-port version uses the Python-bindings for the Qt GUI-Toolkit.

    pip install -r requirements_qt.txt

Optionally you may use the PyQt6-bindings by Riverbank Computing:

    pip install -r requirements_pyqt6.txt
  • Make executable in your file manager

  • Run it with: ./ or ./ respectively

  • Optionally change the Exec-command of your youplay.desktop-file in /home/user/.local/share/applications

Note #1: In case you have installed the Qt-version adapt the Exec-command like this:

    Exec=/home/ralf/dev/youplay/ --gui=qt

Note #2: In case you have installed the PyQt6-version adapt the Exec-command like this:

    Exec=/home/ralf/dev/youplay/ --gui=pyqt6

Operation Instructions

YouPlay supports two modes: CLI (command line mode) and GUI (graphical mode).

You can start YouPlay in CLI mode like this:

  • Navigate in a terminal to your YouPlay directory: cd /home/blabla/youplay


    ./ --help

    ./ songtitle

All other options will be shown interactively.

You can also start YouPlay in GUI mode:

  • Navigate in a terminal to your YouPlay directory: cd /home/blabla/youplay


  • or from your application menu or launcher (this requires youplay.desktop with adapted paths, copied to /home/user/.local/share/applications/)

Note: in case you have installed YouPlay via online-installer you might run it from everywhere, no need to cd into a special directory first.

When the GUI shows up, you can enter a song title (min 4 characters) that you want to listen to. The App will present a list of 10 matching songs from Youtube. Select one or doubleclick to start downloading and playing it. All songs that you are listened to, are stored as mp3 files in a subfolder named 'youplay' under your standard music folder in home. A song, that was already downloaded, will not be downloaded again, as long as the file exists in the 'youplay' subfolder. You can show and play all downloaded songs with the SONG button. Just enter another search term to return to the search list.


Since Youtube changes the API every now and then, it is recommended to update yt-dlp regularly:

yt-dlp -U


Author: Ralf Hersel

License: GPL3