Mopidy 3 Upgrade FAQ

Mopidy 3.0 is a backwards-incompatible release. This post aims to address common questions that users and/or developers may have when they come to upgrade.


What’s new in Mopidy 3.0?

The most significant change in Mopidy 3.0 is adding support for Python 3.7+ and dropping support for Python 2.x. Other release highlights include:

  • Moving the MPD frontend and Local backend out of Mopidy Core and into their own projects.

  • The new extension registry.

  • A configurable default web app for the HTTP frontend.

  • Simplified logging configuration.

  • Improvements to Mopidy’s Core API including removal of many long-deprecated APIs.

For a comprehensive list of changes please see the changelog.

Mopidy 3 also brings new versions of all extensions, some of which include new features. Most noticeably, Mopidy-Spotify 4 supports (read-only) playlists again, and also offers additional browse sections.

Should I upgrade yet?

Yes! The Debian packages for Mopidy and those extensions maintained under the Mopidy GitHub organisation should now be available from for all supported architectures.

Likewise, packages for Arch Linux and everything required to install from source is ready.

How do I upgrade to Mopidy 3?

This depends on how you installed Mopidy 2.x. See our documentation.

Why did you drop support for Python 2?

Python 2 will not be maintained after January 1, 2020 and there is no future for Python projects that are not compatible with Python 3. Python 2 and Python 3 are similar but do have significant differences and so there’s considerable burden in also supporting Python 2. If you are limited to Python 2 then stay with Mopidy v2.3.1.

There are numerous versions of Python 3, which one do I need?

The minimum supported version is Python 3.7 but we also support newer versions such as Python 3.8. Python 3.7 was primarily chosen as it, at the time of porting, is the version of Python shipped in Debian stable (Buster). Python 3.7, or newer, is also available by default in Ubuntu 18.10, Arch Linux, Fedora 29, and in macOS via Homebrew. You can see what the default version of Python 3 is on your system by running python3 --version.

What about Mopidy 3 on Ubuntu 18.04 LTS?

Ubuntu 18.04 (Bionic Beaver) is nearly 2 years old and Long Term Support releases are enterprise focused with stability in mind; they are not designed for running cutting-edge software, such as Mopidy 3. The next Ubuntu LTS release is 20.04 (Focal Fossa) and scheduled for April 2020. It will ship with Python 3.8 and so Mopidy will work out of the box with that. If you are stuck using Ubuntu 18.04 then you’ll find it uses Python 3.6 by default. Getting Mopidy 3 running is possible, but requires some work. One such way is detailed below.

Alternatively, you can continue using Mopidy v2.3.1 until Ubuntu 20.04 is released - just be sure to use Mopidy’s 2.x documentation and only install old Python 2 versions of any extensions from PyPI.

A Docker based installation of Mopidy 3 on Ubuntu 18.04 should also be possible.

So how do I install Mopidy 3 on Ubuntu 18.04 LTS?

Newer versions of Python are available from Ubuntu’s software repositories and installing Python 3.7 is as easy as running:

sudo apt install -y python3.7

Next, follow the first three steps of the instructions for installing from source. Then install Mopidy under Python 3.7 with:

sudo python3.7 -m pip install --ignore-installed mopidy

The GStreamer side of things is a little trickier. We need versions of python3-gi and python3-gst-1.0 that are compatible with Python 3.7 but the versions available in Ubuntu 18.04 (-gi, -gst-1.0) only support the system Python version.

First up is pygobject: the Python 3 bindings for gobject-introspection (python3-gi). This is easy to build from source using pip, once the required dependencies have been installed:

sudo apt install -y \
    libcairo2-dev \
    libffi-dev \
    libgirepository1.0-dev \
    libglib2.0-dev \

sudo python3.7 -m pip install --ignore-installed --no-cache pygobject

The GStreamer Python binding overrides (python3-gst-1.0) are not so simple as they are not available from PyPI. The easiest way is to get 3.7 compatible files from an alternate version of python3-gst-1.0, and copy them into the Python 3.7 installation:

ar x python3-gst-1.0_1.14.4-1_amd64.deb
tar -pxvf data.tar.xz
sudo mv usr/lib/python3/dist-packages/gi/overrides/* /usr/local/lib/python3.7/dist-packages/gi/overrides/

If you want to run Mopidy in a terminal then you are all done and python3.7 -m mopidy should now work. But if you want to run Mopidy as a service then there are a few more steps and things get a little messier.

Download the latest Debian package for Mopidy 3 (as of writing this is v3.0.2 but adjust as required):


Find any missing dependencies by attempting to install; this will likely fail:

sudo dpkg -i mopidy_3.0.2-1_all.deb

Install those missing dependencies and then install again; this should succeed:

sudo apt install --fix-broken
sudo dpkg -i mopidy_3.0.2-1_all.deb

Force the Mopidy service to use our Python 3.7 installation:

sudo sed -i 's/python3/python3.7/' /usr/bin/mopidy

Finally, remove packages we no longer need, including those left over from Mopidy 2.x:

sudo apt autoremove \
    libcairo2-dev \
    libffi-dev \
    libgirepository1.0-dev \

Be sure to install all Mopidy extensions from source using sudo python3.7 -m pip install mopidy-foo-extension.

What about Mopidy 3 on Debian Stretch?

Debian Stretch (oldstable) is not supported. Mopidy 3 requires GStreamer >= v1.14.0 but Stretch provides v1.10.x. There are great new features in v1.14 and now we get to finally start using them.

What happened to the MPD frontend and the Local backend?

The Mopidy-MPD and Mopidy-Local extensions are no longer bundled with Mopidy and have been moved to independent extension. We hope this will help ease development and encourage contributions. After the move, Mopidy-Local merged with Mopidy-Local-SQLite and Mopidy-Local-Images; the functionality of these three projects is now available under one roof in Mopidy-Local. If you used either of these extensions you will now need to explicitly install them.

To install Mopidy-MPD: sudo python3 -m pip install mopidy-mpd

To install Mopidy-Local: sudo python3 -m pip install mopidy-local.

The configuration for Mopidy-Local has changed and you may need to merge/move your previous settings. Refer to Mopidy-Local’s documentation for the available config values.

Why doesn’t Mopidy extension X work?

Some Mopidy extensions do not support Mopidy 3 yet. You can find information on which ones do at our extension registry. Any Python 3 compatible extensions installed using your package manager should be updated when you upgrade Mopidy. But any extensions that were installed from PyPI will need to be explicitly re-installed for Python 3 e.g. sudo python3 -m pip install Mopidy-dLeyna.

When will Mopidy extension X support Mopidy 3?

Extensions maintained under the Mopidy GitHub organisation have been ported to Python 3 and support Mopidy 3.0. For those commmunity maintained extensions not yet ported to Python 3, visit the project’s GitHub page for more info and also consider lending the maintainer a helping hand. Please be patient during this transitional period.

Do I need to remove anything from Mopidy 2?

If installed from source or PyPI you may want to remove Mopidy 2 from your system, but it’s not strictly necessary. Mopidy on Python 3 won’t in any way be affected by any remnants of Mopidy on Python 2.

Mopidy installed using your system package manager (e.g. apt) will automatically remove the old Python 2 version of Mopidy as part of the upgrade.

What about these service configuration changes?

When updating the Debian package you will probably get the following:

Configuration file '/etc/mopidy/mopidy.conf'
 ==> Modified (by you or by a script) since installation.
 ==> Package distributor has shipped an updated version.
   What would you like to do about it ?  Your options are:
    Y or I  : install the package maintainer's version
    N or O  : keep your currently-installed version
      D     : show the differences between the versions
      Z     : start a shell to examine the situation
 The default action is to keep your current version.
*** mopidy.conf (Y/I/N/O/D/Z) [default=N] ? 

If you enter D here it will display the differences. You’ll see the default service-specific [core] and [logging] configuration has been removed (it now lives elsewhere). The remaining differences will be anything you added yourself e.g. account details for extensions, the path to your music files, a custom audio output etc. You’ll probably still need all of that. The main exception is any configuration for Mopidy-Local as some things changed following the move, please check the project’s documentation for details.

If you are not sure what to do, select option Y and get the new default Mopidy 3 service configuration. You will still find your old configuration at /etc/mopidy/mopidy.conf.dpkg-old, which you can compare against the output of sudo mopidyctl config to see what configuration you actually still need to specify in /etc/mopidy/mopidy.conf to obtain the setup you want. Afterwards, feel free to delete mopidy.conf.dpkg-old.




Nick Steel