Documentation

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

We also have generated documentation here.

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.

ØMQ Compatibility

pyzmq aims to support multiple versions of libzmq. pyzmq ≥ 14.0 supports
libzmq >= 2.1.4, and has full support for libzmq's 4.0 API.

Binary installers

PyZMQ has binary installers that include current (4.0) libzmq for Windows and OSX.
Python eggs (as found by easy_install) and wheel (for pip ≥ 1.5) installers on PyPI.

easy_install / pip

In many cases, pyzmq can be installed with:

# (Windows or OS X)
pip install --wheel pyzmq
# or
easy_install pyzmq
# or (pretty much anywhere)
pip install pyzmq

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

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.

Source Code

The current stable pyzmq release can be downloaded from PyPI.

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:

pip install cython

If you download a release from PyPI, 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 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

Android

This has been tried, managed "import zmq", but not yet tested. Preview at https://github.com/zeromq/pyzmq/issues/227

Windows

Building pzymq on Windows requires either MinGW or MSVC (2008 or 2010 depending on the Python version). The steps are mostly the same as for POSIX platforms. Please contact us if you have difficulties building or using PyZMQ on Windows. Here is a step-by-step guide.

Test Suite

PyZMQ has an integrated test suite. To run the test suite simple do:

$ python setup.py build_ext --inplace
$ python setup.py test

otherwise you may see an ImportError when compiled extensions are imported.

You can also run the test suite with nose, trial, or py.test after installing, which do not require the build to be inplace:

$ nosetests zmq.tests

Bug Reporting

If you encounter problems please fill a bug report at:

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

or write an e-mail to the mailing list.

Mailing List

Discussions about this language binding take place on the general zeromq-dev list.