Since pyspotify is a Python wrapper around the libspotify library, pyspotify necessarily depends on libspotify.

Installing libspotify

libspotify is provided as a binary download for a selection of operating systems and CPU architectures from the libspotify site. If libspotify isn’t available for your OS or architecture, then you’re out of luck and can’t use pyspotify either.

To install libspotify, use one of the options below, or follow the instructions on the libspotify site and in the README file of the libspotify tarball.


If you’re running a Debian-based Linux distribution, like Ubuntu or Raspbian, you can get Debian packages of libspotify from Follow the instructions on the site to add as a software repository on your system. In summary:

wget -q -O - | sudo apt-key add -
sudo wget -q -O /etc/apt/sources.list.d/mopidy.list
sudo apt-get update

Then install libspotify:

sudo apt-get install libspotify-dev

Arch Linux

libspotify is packaged in AUR. To install libspotify, run:

yaourt -S libspotify


libspotify is packaged in rpmfusion non-free. Install the repository package, then run:

yum -y install libspotify-devel

Mac OS X

If you’re using Homebrew, it has a formula for libspotify in the homebrew/binary tap:

brew install homebrew/binary/libspotify


There’s an issue with building pyspotify against libspotify on OS X where the pyspotify installation fails with “Reason: image not found”.

A known workaround is to create a symlink after installing libspotify, but before installing pyspotify:

ln -s /usr/local/opt/libspotify/lib/libspotify.12.1.51.dylib \

Alternatively, the mopidy/mopidy Homebrew tap has a libspotify formula which includes the workaround:

brew install mopidy/mopidy/libspotify

For details, or if you have a proper fix for this, see #130.


It is currently unknown if pyspotify works with the Mac OS X download option from the libspotify web site. If you can provide any information either way, please open an issue.

Installing pyspotify

You can install pyspotify from PyPI. PyPI may have a pyspotify package precompiled for your OS and architecture available as a wheel package. To install it run:

pip install pyspotify

If this fails, then pyspotify probably isn’t available prebuilt for your OS and architecture. In that case, you’ll need a C compiler, Python development headers, and libffi development headers to build pyspotify. When you got that in place, you can rerun the pip install pyspotify command to install pyspotify.

Once you have pyspotify installed, you should head over to Quickstart for a short introduction to pyspotify.


If you’re on a Debian-based system, you can install the pyspotify build dependencies by running:

sudo apt-get install build-essential python-dev python3-dev libffi-dev

Arch Linux

If you’re on Arch Linux, you can install the pyspotify build dependencies by running:

sudo pacman -S base-devel python2 python

Mac OS X

If you’re on Mac OS X, you’ll need to install the Xcode command line developer tools. Even if you’ve already installed Xcode from the App Store, e.g. to get Homebrew working, you should run this command:

xcode-select --install

If you get an error about ffi.h not being found when installing the cffi Python package, try running the above command.


Due to a currently unresolved issue, the CFFI-generated C extension module in pyspotify is linked with libspotify without the .dylib file suffix.

If pip install pyspotify fails with the message “Reason: image not found”, then run the following command and rerun the pip command:

ln -s /usr/local/opt/libspotify/lib/libspotify.dylib \

If you know how to permanently fix this, please comment on #130.