Creating a Development Environment

This will show you how to get the latest and freshest Quod Libet running on your machine and allow you to change it as you wish. The main task here is to install all the software which Quod Libet uses and depends on.


The easiest and recommended way to get all the dependencies needed for the development version is to install one of our unstable repositories. By doing so all the needed dependencies are automatically installed along the way. See the download section for a list of available repositories.

In case your distribution is not supported you have to find/install the dependencies yourself. See the Packaging Guide for a list of dependencies.

Now clone the Git repository and start Quod Libet:

$ git clone
$ ./quodlibet/quodlibet/


On MacOS (formerly OS X) all the needed dependencies are included in the provided bundle itself. Download the latest bundle, which is guaranteed to work with current Git main: QuodLibet-latest.dmg. It contains a run script which passes all arguments to the included Python with the right environment set up.

$ git clone
$ ./ <path_to_git_repo>/quodlibet/

On recent MacOS releases, the OS Gatekeeper will complain about the application not being recognised. It is easiest to just clear the extended attribute from all files in the bundle rather than try and open each and every component that MacOS will refuse to open:

$ xattr -rd ./

The bundle includes pip, so you can always install additional packages (such as flake8, pytest and flaky, which would let you run the test suite):

$ ./ -m pip install flake8 pytest flaky
$ ./ <path_to_git_repo>/ test

If you want to run the tests with your own Python command, you’ll need to install some additonal software and packages:

$ brew install cairo dbus gst-libav gst-plugins-bad gst-plugins-good gst-plugins-ugly \
    gstreamer gtk-mac-integration gtk+3 libsoup pkg-config pygobject3
$ poetry install
$ poetry run pip install pyobjc

This will almost cover all the dependencies that the bundle will contain; at the time of writing the brew gstreamer plugins do not include the wavpack (gst-plugins-good) or game-music-emu (gme, in gst-plugins-bad) plugins. The above list may be out of date, check the quodlibet metamodule section of the quodlibet.modules moduleset file for a more up-to-date list of dependencies.

If you want to build a bundle yourself or change/add dependencies, see the osx_bundle directory in the Git repo for further instructions.


On Windows we use the msys2 environment for development.

Check out the win_installer directory in the Git repo for further instructions.


Across all environments, we now support Virtualenvs with Pip dependencies, managed by Poetry.

Installation, once cloned is just:

$ poetry install

If you want all the optional dependencies for various plugins:

$ poetry install -E plugins