If you are thinking about making Mopidy better, or you just want to hack on it, that’s great. Here are some tips to get you started.

Getting started

  1. Make sure you have a GitHub account.
  2. Submit a ticket for your issue, assuming one does not already exist. Clearly describe the issue including steps to reproduce when it is a bug.
  3. Fork the repository on GitHub.

Making changes

  1. Clone your fork on GitHub to your computer.

  2. Consider making a Python virtualenv for Mopidy development to wall of Mopidy and it’s dependencies from the rest of your system. If you do so, create the virtualenv with the --system-site-packages flag so that Mopidy can use globally installed dependencies like GStreamer. If you don’t use a virtualenv, you may need to run the following pip and python commands with sudo to install stuff globally on your computer.

  3. Install dependencies as described in the Installation section.

  4. Install additional development dependencies:

    pip install -r dev-requirements.txt
  5. Checkout a new branch (usually based on develop) and name it accordingly to what you intend to do.

    • Features get the prefix feature/
    • Bug fixes get the prefix fix/
    • Improvements to the documentation get the prefix docs/

Running Mopidy from Git

If you want to hack on Mopidy, you should run Mopidy directly from the Git repo.

  1. Go to the Git repo root:

    cd mopidy/
  2. To get a mopidy executable and register all bundled extensions with setuptools, run:

    python develop

    It still works to run python mopidy directly on the mopidy Python package directory, but if you have never run python develop the extensions bundled with Mopidy isn’t registered with setuptools, so Mopidy will start without any frontends or backends, making it quite useless.

  3. Now you can run the Mopidy command, and it will run using the code in the Git repo:


    If you do any changes to the code, you’ll just need to restart mopidy to see the changes take effect.


Mopidy has quite good test coverage, and we would like all new code going into Mopidy to come with tests.

  1. To run all tests, go to the project directory and run:


    To run tests with test coverage statistics:

    nosetests --with-coverage

    Test coverage statistics can also be viewed online at

  2. Always check the code for errors and style issues using flake8:


    If successful, the command will not print anything at all.

  3. Finally, there is the ultimate but a bit slower command. To run both tests, docs build, and flake8 linting, run:


    This will run exactly the same tests as Travis CI runs for all our branches and pull requests. If this command turns green, you can be quite confident that your pull request will get the green flag from Travis as well, which is a requirement for it to be merged.

Submitting changes

Additional resources