Library / SDK
zeromq/pyzmq avatar
zeromq/pyzmq

pyzmq: Python bindings whose version number stopped matching libzmq in 2013

PyZMQ: Python bindings for zeromq

4,185 stars666 forksPythonBSD-3-Clause

At a glance

What is it?
pyzmq wraps the ZeroMQ C library for Python and PyPy, building through scikit-build-core with CMake, and it supports the stable 3.x and 4.x libzmq APIs with no code changes. Two environment variables change what the build downloads, the README keeps a compatibility table for interpreters long gone, and the example suite includes a draft API folder the supported path explicitly excludes.
Who is it for?
Use pyzmq when you want ZeroMQ from Python and can accept that it is a binding rather than a pure Python library, which means a C library underneath and a compiler on the source path. Take the wheel unless you have a reason not to, because the documented reason to compile is that you already have libzmq built the way you want it.
Can I use it commercially?
Yes. BSD-3-Clause is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
Is it still maintained?
Yes. The repository last received commits 12 days ago.
What is it written in?
Mainly Python, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • zeromq/pyzmq4,185 ★ · +9
Star history
Repository2026-09-242026-11-15
zeromq/pyzmq4.2k4.2k

9 Stars in the last 52 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

Forcing a source build is the documented escape hatch

A plain install is the normal path, because wheels are published for macOS, Windows and Linux.

bash
pip install pyzmq

Two warnings sit around that command. An up to date pip matters, because an older one may not find the right wheels and will silently fall back to building. And compiling from source with the same command is expected to work in most environments.

The explicit escape hatch is a second flag on the same command.

bash
pip install --no-binary=pyzmq pyzmq

The reason given for preferring it is specific: you already have libzmq installed and configured the way you want it. That is the case where the bundled binary library and your system one differ, and it is the case the flag exists for.

The distribution channel is also a decision rather than a default. Unless you are developing pyzmq itself, the guidance is to take the source or wheels from PyPI, or to install with conda.

Two environment variables change what the build downloads

The build is PEP 621 metadata with scikit-build-core as the backend, and CMake underneath it, with a floor of 3.15 that the build system itself requires.

The default requirements branch on the interpreter. CPython gets Cython 3.0 or newer, and PyPy gets CFFI, which is also the only runtime dependency declared in the project metadata.

Two overrides change that.

toml
[[tool.scikit-build.overrides]]
if.env.PYZMQ_BACKEND = "cffi"
build.requires = ["cffi"]

[[tool.scikit-build.overrides]]
if.any.env.PYZMQ_LATEST_CYTHON = true
build.requires = ["cython @ https://github.com/cython/cython/archive/HEAD.tar.gz"]

Setting PYZMQ_BACKEND to cffi selects the CFFI path regardless of interpreter. Setting PYZMQ_LATEST_CYTHON points the Cython requirement at a tarball of the repository head rather than a released version, which is a development convenience with the obvious risk attached: a build that succeeds today may behave differently tomorrow.

Both variables are worth checking before concluding that a build failure is environmental.

Version 13.0.0 decoupled the numbering from libzmq

pyzmq and libzmq once shared a version number. They no longer do, and the README is explicit about when that changed and why.

Releases up to 2.2.0 matched libzmq versioning. Starting with 13.0.0, pyzmq follows semantic versioning conventions that account only for pyzmq itself. The parenthetical in the README notes that it was the thirteenth release, so why not.

So when you see a pyzmq release with a much larger number than your installed libzmq, nothing is mismatched. The two number lines stopped corresponding thirteen releases in, and reading a modern pyzmq version as a libzmq version is the mistake to avoid.

That release also brought PyPy support through CFFI, and CFFI's own constraint is the one place a libzmq version still matters: it supports libzmq 3.2.2 and newer. So the same page carries both the decoupling and the one remaining floor.

The compatibility table is a map of abandoned interpreters

The lower half of the README is a compatibility table for Python versions nobody runs any more, and it is still maintained.

bash
pip install 'pyzmq<16'

Version 16 is where support for Python 2.6 and 3.2 was dropped, so anything still on those interpreters pins below it. For libzmq 2.0.x the guidance is a pin below pyzmq 2.1, with the less-than written as a shell escape. Then there is the tail: 2.1.11 was the last release to support Python 2.5, everything from 2.2.0 onwards requires Python 2.6 or newer.

The current requirement is stated at the top instead, Python 3.9 or newer, and PyPy is supported alongside it.

So the file carries two eras of information: a floor of 3.9 for new work, and a lookup table for the archive. Read the top for an install decision and the bottom only if you are pinning something old.

Only the pyzmq component is built and installed

The scikit-build configuration narrows what the build produces.

toml
[tool.scikit-build]
wheel.packages = ["zmq"]
wheel.license-files = ["LICENSE*", "licenses/LICENSE*"]
cmake.version = ">=3.15"
build.targets = ["pyzmq"]
install.components = ["pyzmq"]

Both the build target list and the install component list name the same single component. That matters because a CMake project can define several, and this configuration says only the library target is built and only that component is installed.

The wheel takes the zmq package and nothing else, and the licence files are collected by pattern, matching both the root licence and the ones under a licences directory. The repository also keeps a RELICENSE directory, which suggests the pattern has absorbed files added over time.

The project metadata declares BSD-3-Clause and describes the package as Python bindings for 0MQ, with a support address on the project's mailing list rather than an individual.

examples/draft exists although DRAFT APIs are excluded

The support statement is precise about which APIs are covered: pyzmq supports the stable, explicitly not draft, 3.x and 4.x APIs of libzmq, with no code changes and no flags to pass when building against a current libzmq.

The examples directory contains a folder named draft anyway, alongside sixteen others: asyncio, cython, device, eventloop, gevent, heartbeat, logger, mongodb, monitoring, poll, pubsub, recv_into, security, serialization and win32-interrupt.

That combination is the interesting part. The examples are there to be read and copied, and the directory structure mirrors the whole surface including the parts outside the supported statement, which is a reasonable way to show what is possible without claiming it is covered.

The win32-interrupt folder is the other one worth noticing. It exists because signal handling differs on Windows, and the presence of a dedicated example for it says more about the library's portability surface than any claim in the README would.

Three documentation homes, plus a workflow security policy

The documentation is split by audience rather than gathered in one place. API details and notes on Python and Cython development are on Read the Docs, generated from Sphinx sources in the repository. Learning ZeroMQ itself is pointed at the project's guide, which has a Python version of every example. A wiki exists for everything else, and the changelog is published as its own page for changes between releases.

The repository is organised to match. docs/ holds the documentation sources, examples/ the runnable samples, packaging/ and buildutils/ the build plumbing, cmake/ the CMake side, buildutils/ the auxiliary tooling, and perf/ the benchmarks. Tests live in tests/ with their own pytest and coverage configuration, and there is a separate directory for type checking tests, plus mypy.ini and a flake8 configuration.

Two files at the root are about the automation rather than the code. zizmor.yaml and zizmor-strict.yaml configure a security linter for GitHub Actions workflows, in a normal and a strict mode. AGENTS.md sits alongside them, and SECURITY.md defines how to report a problem. Between those and a code of conduct file, the repository documents its process as carefully as its API.

Editorial conclusion

Use pyzmq when you want ZeroMQ from Python and can accept that it is a binding rather than a pure Python library, which means a C library underneath and a compiler on the source path. Take the wheel unless you have a reason not to, because the documented reason to compile is that you already have libzmq built the way you want it. Before you build from source, know the floor is Python 3.9 with Cython 3 for CPython and CFFI for PyPy, and that the C library must be 3.2.2 or newer. Check the two build environment variables before assuming a build failure is yours, since one of them switches the backend and the other pulls Cython from a repository head rather than a release. For anything beyond version 27.2.0, read the changelog rather than mapping pyzmq versions onto libzmq ones, since that mapping stopped at 2.2.0.

Frequently asked questions

What is pyzmq?

It is the Python binding package for ZeroMQ, the C messaging library. It requires Python 3.9 or newer or PyPy, and it supports libzmq 3.2.2 and newer including the 4.x series. Current version is 27.2.0, released August 20, 2026.

How do I install pyzmq?

With pip install pyzmq, which gives you a published wheel on macOS, Windows and Linux if your pip is current enough to find it. To compile against your own libzmq build instead, use pip install --no-binary=pyzmq pyzmq. Conda is offered as an alternative channel.

What is the difference between zmq and pyzmq?

libzmq is the C implementation, pyzmq is the Python binding to it. Since version 13.0.0 pyzmq uses its own semantic versioning, so only releases up to 2.2.0 shared a version number with libzmq.

How to install ZMQ in python?

Install the pyzmq package rather than the C library directly. A wheel arrives with the library already built in, and if you want to link against your own libzmq, install from source with pip install --no-binary=pyzmq pyzmq.

What is pyzmq package used for?

It exposes the ZeroMQ messaging API to Python. ZeroMQ itself is described as a lightweight and fast messaging implementation, and pyzmq supports its stable 3.x and 4.x APIs without code changes or extra flags.

Official sources

  1. License: BSD-3-Clause
  2. Project website
  3. README
  4. Releases
  5. zeromq/pyzmq on GitHub
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/zeromq-pyzmq.svg)](https://hysenlabs.com/projects/zeromq-pyzmq)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/zeromq-pyzmq.svg)](https://hysenlabs.com/projects/zeromq-pyzmq)

Was this useful?