Skip to main content

A Python MPD client library

Project description

Build Status

python-mpd2 is a Python library which provides a client interface for the Music Player Daemon.

Difference with python-mpd

python-mpd2 is a fork of python-mpd. While 0.4.x was backwards compatible with python-mpd, starting with 0.5 provides enhanced features which are NOT backward compatibles with the original python-mpd package. (see PORTING.txt for more information)

The following features were added:

  • Python 3 support (but you neead at least Python 2.6)
  • support for the upcoming client-to-client protocol
  • support for new commands from MPD v0.17 (seekcur, prio, prioid, config, searchadd, searchaddpl)
  • remove deprecated commands (volume)
  • explicitly declared MPD commands (which is handy when using for example IPython)
  • a test suite
  • API documentation to add new commands (see Future Compatible
  • support for Unicode strings in all commands (optionally in python2, default in python3 - see Unicode Handling)
  • configureable timeouts
  • support for logging
  • improved support for sticker
  • improved support for ranges

If you like this module, you could try contact the original author or join the discussion on the issue tracker so that it gets merged upstream.

Getting the latest source code

If you would like to use the latest source code, you can grab a copy of the development version from Git by running the command:

$ git clone git://

Installing from source

To install python-mpd2 from source, simply run the command:

$ python install

You can use the –help switch to for a complete list of commands and their options. See the Installing Python Modules document for more details.

Getting the latest release

The latest stable release of python-mpd2 can be found on PyPI


$ pip install python-mpd2

Until Linux distributions adapt this package, here are some ready to use packages to test your applications:


Drop this line in /etc/apt/sources.list.d/python-mpd2.list:

deb unstable main

Import the gpg key as root:

$ wget -O - | apt-key add -

Key fingerprint:

2255 310A D1A2 48A0 7B59  7638 065F E539 32DC 551D

Controls with apt-key finger.

Then simply update/install python-mpd2 or python3-mpd with apt or aptitude:

Arch Linux

Install python-mpd2 from AUR.

Gentoo Linux

Replaces the original python-mpd beginning with version 0.4.2:

$ emerge -av python-mpd


Install py-mpd2:

$ pkg_add -r py-mpd2

Packages for other distributions are welcome!

Using the client library

The client library can be used as follows:

>>> client = mpd.MPDClient()           # create client object
>>> client.timeout = 10                # network timeout in seconds (floats allowed), default: None
>>> client.idletimeout = None          # timeout for fetching the result of the idle command is handled seperately, default: None
>>> client.connect("localhost", 6600)  # connect to localhost:6600
>>> print(client.mpd_version)          # print the MPD version
>>> print(client.find("any", "house")) # print result of the command "find any house"
>>> client.close()                     # send the close command
>>> client.disconnect()                # disconnect from the server

A list of supported commands, their arguments (as MPD currently understands them), and the functions used to parse their responses can be found in doc/commands.txt. See the MPD protocol documentation for more details.

Command lists are also supported using command_list_ok_begin() and command_list_end():

>>> client.command_list_ok_begin()       # start a command list
>>> client.update()                      # insert the update command into the list
>>> client.status()                      # insert the status command into the list
>>> results = client.command_list_end()  # results will be a list with the results

Commands may also return iterators instead of lists if iterate is set to True:

client.iterate = True
for song in client.playlistinfo():
    print song["file"]

Each command have a send_ and a fetch_ variant, which allows to send a MPD command and then fetch the result later. This is useful for the idle command:

>>> client.send_idle()
# do something else or use function like select():
# ex. select([client], [], []) or with gobject:
>>> events = client.fetch_idle()

Some more complex usage examples can be found here


Some commands support integer ranges as argument. This is done in python-mpd2 by using two element tuple:

# move the first three songs
# after the last in the playlist
>>> client.status()
['file: song1.mp3',
 'file: song2.mp3',
 'file: song3.mp3',
 'file: song4.mp3']
>>> client.move((0,3), 1)
>>> client.status()
['file: song4.mp3'
 'file: song1.mp3',
 'file: song2.mp3',
 'file: song3.mp3',]

Second element can be omitted. MPD will assumes the biggest possible number then (don’t forget the comma!):: NOTE: mpd versions between 0.16.8 and 0.17.3 contains a bug, so ommiting doesn’t work.

>>> client.delete((1,))     # delete all songs, but the first.

Unicode Handling

To quote the mpd protocol documentation:

> All data to be sent between the client and server must be encoded in UTF-8.

With Python 3:

In Python 3, Unicode string is the default string type. So just pass these strings as arguments for MPD commands and python-mpd2 will also return such Unicode string.

With Python 2.x

For backward compatibility with python-mpd, when running with Python 2.x, python-mpd2 accepts both Unicode strings (ex. u”♥”) and UTF-8 encoded strings (ex. “♥”).

In order for MPDClient to return Unicode strings with Python 2, create the instance with the use_unicode parameter set to True.

Using Unicode strings should be prefered as it is done transparently by the library for you, and makes the transition to Python 3 easier:

>>> import mpd
>>> client = MPDClient(use_unicode=True)
>>> client.urlhandlers()[0]
>>> client.use_unicode = False # Can be switched back later
>>> client.urlhandlers()[0]

Using this option in Python 3 doesn’t have any effect.


By default messages are sent to the logger named mpd:

>>> import logging, mpd
>>> logging.basicConfig(level=logging.DEBUG)
>>> client = mpd.MPDClient()
>>> client.connect("localhost", 6600)
INFO:mpd:Calling MPD connect('localhost', 6600, timeout=None)
>>> client.find('any', 'dubstep')
DEBUG:mpd:Calling MPD find('any', 'dubstep')

For more information about logging configuration, see

Future Compatible

New commands or special handling of commands can be easily implemented. Use add_command() or remove_command() to modify the commands of the MPDClient class and all its instances.:

def fetch_cover(client):
    """"Take a MPDClient instance as its arguments and return mimetype and image"""
    # this command may come in the future.

self.client.add_command("get_cover", fetch_cover)
# you can then use:

# remove the command, because it doesn't exist already.


Currently MPDClient is NOT thread-safe. As it use a socket internaly, only one thread can send or receive at the time.

But MPDClient can be easily extended to be thread-safe using locks. Take a look at examples/ for further informations.


Just run:

$ python test

This will install Tox. Tox will take care of testing against all the supported Python versions (at least available) on our computer, with the required dependencies

Contacting the author

Just contact me (Mic92) on Github or via email (

Usually I hang around on Jabber:

You can contact the original author by emailing J. Alexander Treuman

He can also be found idling in #mpd on as jat.

Project details

Release history Release notifications

History Node


History Node


History Node


History Node


History Node


History Node


This version
History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Filename, size & hash SHA256 hash help File type Python version Upload date
python-mpd2-0.5.1.tar.bz2 (29.3 kB) Copy SHA256 hash SHA256 Source None Mar 21, 2013
python-mpd2-0.5.1.tar.gz (34.9 kB) Copy SHA256 hash SHA256 Source None Mar 21, 2013 (44.1 kB) Copy SHA256 hash SHA256 Source None Mar 21, 2013

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging CloudAMQP CloudAMQP RabbitMQ AWS AWS Cloud computing Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page