Building and Installing PyZMQ
Clone this wiki locally
We build eggs for OS X and Windows, so we recommend that those platforms
easy_install pyzmq. But many users prefer pip, which unfortunately
still ignores eggs. In an effort to make pyzmq easier to install, pyzmq
will try to build libzmq as a Python extension if it cannot find a
libzmq to link against.
This is thanks to work done in pyzmq_static.
Linking against system libzmq is still the preferred mechanism, so pyzmq will try pretty hard to find it. You can skip the searching by explicitly specifying that pyzmq build its own libzmq:
$> pip install pyzmq --install-option="--zmq=bundled"
Eggs and MSIs
We have binary installers for various Pythons on OSX and Windows, so you
should be able to just
easy_install pyzmq in many situations. These
eggs include matching libzmq, so they should be the only thing you
need to start using pyzmq, but we simply don't have the experience to
know when and where these installers will not work.
If a binary installer fails for you, please tell us about your system and the failure, so that we can try to fix it in later releases, and fall back on building from source.
Eggs are on PyPI, and we have them for 'current' Pythons, which are for OSX 10.7:
- Python 2.7, 3.2 (32b+64b intel)
and OSX 10.6:
- Python 2.6 (32b+64b intel)
and Windows (x86 and x64):
- Python 2.7, 3.2
We also have MSI installer packages in our downloads section on GitHub.
A Python 2.6/win64 MSI for 2.1.7 was provided by Craig Austin (craig DOT austin AT gmail DOT com)
Our build scripts are much improved as of 2.1.4, so if you would like to
contribute better Windows installers, or have any improvements on
existing releases, they would be much appreciated. Simply
python setup.py bdist_msi or
python setupegg.py bdist_egg should
work, once you have libzmq and Python. We simply don't have the VMs or
time in which to cover all the bases ourselves.
Building PyZMQ from source
To build and install pyzmq from source, you will first need to build libzmq. After you have done this, follow these steps:
Tell pyzmq where libzmq is via the configure subcommand:
$ python setup.py configure --zmq=/path/to/zeromq
or the zmq install directory on OSX/Linux:
$ python setup.py configure --zmq=/usr/local
The argument should be a directory containing
zmq.h respectively. For instance (on
Windows), if you have downloaded pyzmq and current libzmq into the same
parent directory, this would be:
$ python setup.py configure --zmq=../zeromq-2.2.0
Second, run this command:
$ python setup.py install
Cython is not required to build pyzmq from a release package, but it is required if you want to develop pyzmq, or build directly from our repository on GitHub.
On Windows, libzmq.dll will be copied into the zmq directory, and
installed along with pyzmq, so you shouldn't need to edit your
It is best to compile both ØMQ and PyØMQ with Microsoft Visual Studio 2008 (2010 for Python ≥ 3.3). You should not need to use mingw. If you build libzmq with VS that does not match the one used to build Python, then there may be issues in error handling, because there will be a mismatch between error numbers.
Current testing indicates that running
$ python setup.py bdist_msi
successfully builds a working MSI installer, but we don't have enough Windows deployment experience to know where that may fail.
64b Windows builds have been successful (as of 22.214.171.124), using VC++ 2008 express, and the Windows 7 SDK. VS2008 had to be patched as described here, and pyzmq was built following these instructions on the Cython wiki.
If you install libzmq to a location other than the default
/usr/local) on Linux, you may need to do one of the following:
LD_LIBRARY_PATHto point to the
libdirectory of ØMQ.
Build the extension using the
$ python setup.py build_ext --rpath=/opt/zeromq-dev/lib
The easiest way to install libzmq on OSX is with the wonderful homebrew package manager, via:
$ brew install zeromq
And to build a 32+64b intel fat binary, add
$ brew install zeromq --universal
This will install libzmq in /usr/local.
as of 13.0, PyZMQ includes a CFFI backend for PyPy compatiblity. Just install, and it should work.
Non standard install directories with CFFI
However if zeromq is installed to a non default directory then CFFI compilation will fail. In that situation adding something like below will allow you to use non standard directories:
LIBRARY_PATH=../../zeromq_3.2.3_install/lib/ C_INCLUDE_PATH=../../zeromq_3.2.3_install/include/ pypy-c -c "import zmq"
To develop PyZMQ, you will need to install Cython, version 0.15 or
greater. After installing Cython, instead of doing
python setup.py install do:
$ python setup.py build_ext --inplace $ python setupegg.py develop
This will build the C extension inplace and then put this directory on
sys.path. With this configuration you only have to run:
$ python setup.py build_ext --inplace
each time you change the
.pyx files. To clean the sources, you can do:
$ python setup.py clean
To run the test suite after building pyzmq in-place, just do:
$ python setup.py test
$ nosetests zmq.tests
after an install.