Python binding

ØMQ Compatibility

pyzmq aims to support multiple versions of libzmq. pyzmq-2.1.9 supports
libzmq >= 2.1.4, and as of release 2.1.7, has experimental support for libzmq's 3.0 API.
2.1.9's 3.0 support has been updated to include changes in the 4.0 dev branch.

Binary installers

PyZMQ has binary installers that include current libzmq for Windows and OSX.
Python eggs (as found by easy_install) on pypi,
and MSI installers for Windows on GitHub.

easy_install

In many cases, pyzmq can be installed with:

easy_install pyzmq

You may need to install the python-dev package first. If we don't have an egg for your system (e.g. Linux), then easy_install will be building from source, and you will need to install libzmq, but easy_install pyzmq or pip install pyzmq will still work as long as libzmq was installed to a default location, such as /usr/local.

If you see a message like error while loading shared libraries: libzmq.so.1, then try rebuilding the dynamic linking cache with sudo ldconfig prior to building pyzmq.

If you are still using zeromq 2.0.10, you can install download pyzmq-2.0.10.1 from GitHub or install with:

easy_install "pyzmq==2.0.10.1"

Source Code

The current stable pyzmq release can be downloaded from GitHub:
pyzmq-2.1.11.tar.gz
pyzmq-2.1.11.zip

The git repository is at: http://github.com/zeromq/pyzmq. You can download the current PyZMQ development version as a zip or tar package, or clone the git repository:

git clone git://github.com/zeromq/pyzmq.git

If you get the source via git clone, or edit any of the pyzmq cython files (*.pyx), then you will need Cython to generate the C extensions, which can be installed with:

easy_install cython

If you download a zipfile or tarball, Cython is not a build dependency.

Build and installation

You need to install ØMQ first. Please use the current stable package.

Then download the PyZMQ source and cd to its top-level directory:

$ cd pyzmq

building pyzmq

If you are using the current pyzmq (2.1.4, or later), we have a new configuration command that should simplify building pyzmq.

If pyzmq can't find libzmq (e.g. if it's not installed to /usr/local), you can tell pyzmq where zeromq has been installed, with:

$ python setup.py configure --zmq=/path/to/zmq/prefix

This will be a directory containing include and lib, which contain the zmq headers and libraries respectively. If you configured zeromq with the —prefix command, this will be the same location. On Linux/OSX systems, it will likely be something like $HOME/usr/local or /usr/local/libzmq-dev. If zeromq was installed to the default location of /usr/local this step should be unnecessary.

Windows

On Windows, this prefix is likely to be the zeromq source directory. If you downloaded pyzmq and libzmq into the same directory, then you would run:

$ python setup.py configure --zmq=../libzmq

As of pyzmq-2.1.4, you no longer need to edit your PATH or move libzmq.dll around manually.

Building PyZMQ < 2.1.4

For PyZMQ < 2.1.4, there is not a configure command, so you must copy setup.cfg.template to setup.cfg and edit that new file to specify the library_dir and include_dirs variables to point to your ØMQ installation:

[build_ext]
# Edit these to point to your installed zeromq library and header dirs.
library_dirs = /usr/local/libzmq-dev/lib
include_dirs = /usr/local/libzmq-dev/include

If you did a standard make, ØMQ will be in /usr/local/lib and /usr/local/include and a setup.cfg might not be necessary.

Finally install the package by running:

$ python setup.py install

You may have to run this last command with sudo, depending on your install path.

Under Linux, you will need the python-dev package installed.

Windows

Building pzymq on Windows requires either MinGW or MSVC 2008. The steps are mostly the same as for POSIX platforms, however, for pyzmq older than 2.1.4, you will need to copy the ØMQ library libzmq.dll to pyzmq\zmq before building. Please contact us if you have difficulties building or using PyZMQ on Windows. Here is a step-by-step guide.

Documentation

The README file of the source code has a quick summary of information.

We also have Sphinx generated documentation hosted on GitHub:

http://zeromq.github.com/pyzmq/

The Sphinx docs contain autogenerated coverage of the API as presented in Python, as well as descriptions of where PyZMQ may differ from other ØMQ bindings.