Skip to main content

pyomq

Python binding for omq.rs, a Rust libzmq port. Drop-in pyzmq replacement on the common path.

Highlights

  • Sync and asyncio APIs with all 20 ZMTP socket types.
  • Standard sockets: PAIR, PUB, SUB, REQ, REP, DEALER, ROUTER, PULL, PUSH, XPUB, XSUB, and STREAM.
  • Draft sockets: SERVER, CLIENT, RADIO, DISH, GATHER, SCATTER, PEER, and CHANNEL.
  • tcp://, ipc://, inproc://, verified TLS quic://, dart://, and udp:// transports (udp:// is RADIO/DISH only).
  • Optional plain, curve, lz4, zstd, quic, and dart features in the published wheel.
  • Built on omq-tokio; runtime work runs on a dedicated background thread and Python calls release the GIL across the runtime trip.
  • RADIO/DISH groups use socket.join() / socket.leave(), socket.send(body, group="..."), and Frame.group on receive.

Install

Requires Python 3.12+. Wheels use the cp312-abi3 stable ABI.

uv pip install pyomq

The standard build includes optional features: plain, curve, lz4, zstd, quic, dart. Use pyomq.has("curve") at runtime to check availability.

Published wheels target Linux, macOS, and Windows on x86-64 and ARM64. Other platforms can build from sdist.

Usage

import pyomq as zmq  # drop-in for `import zmq` from pyzmq

ctx = zmq.Context()
push = ctx.socket(zmq.PUSH)
push.connect("tcp://127.0.0.1:5555")
push.send(b"hello")
push.close()
ctx.term()

For asynchronous code:

import pyomq
import pyomq.asyncio as zmq_async

ctx = zmq_async.Context()
sock = ctx.socket(pyomq.PUSH)
sock.connect("tcp://127.0.0.1:5555")
await sock.send(b"hello")
sock.close()

Zguide-style runnable examples live in examples/zguide/.

Buffers, tracking, and types

send() accepts pyomq.Sendable: buffer-protocol objects and Frame. send_multipart() also accepts generators of these values. Buffers must be contiguous; multidimensional and multibyte buffers are sent as raw bytes. Use send_string() for text. __bytes__ alone does not make an object sendable.

With copy=False, track=True, sends return a MessageTracker; asyncio sends resolve to that tracker when awaited. tracker.done and tracker.wait(timeout) indicate when borrowed buffers are no longer in use, not peer delivery. Timeouts are in seconds; wait() raises NotDone when the deadline expires. Do not mutate borrowed data before completion. Keeping a zero-copy Frame, an exported view, or an inproc receiver's frame alive can delay completion. Multipart tracking covers every part. Copied buffer sends return None, even with track=True. Sending a Frame returns its own tracker; requesting tracking on an untracked frame raises ValueError.

wait() blocks its calling thread. In asyncio code, awaiting send() only waits for queue admission. Use await asyncio.to_thread(tracker.wait) when you need buffer completion without blocking the event loop.

Python-defined buffer exporters may run __release_buffer__ on an I/O thread. Release callbacks must not make blocking socket or context calls: those calls can deadlock the I/O thread. Use copy=True for such exporters or hand their cleanup work to an application thread. This limitation also applies when tracking is disabled.

Tracking adds bookkeeping only when requested. For repeated sends of unchanged data, a tracked Frame reuses its tracking state across sends. Its tracker still cannot finish until the frame and every outstanding user release it.

The package includes native stubs and precise sync/async receive overloads. copy=False returns Frame values, and a runtime boolean yields the union of byte and frame result types. Serialization callbacks retain their return types; socket options, authentication policies, and monitor events are typed.

PLAIN servers require an explicit policy before bind. Use fixed credentials with pull.plain_server = 1; pull.set_plain_auth([("alice", "secret")]), or pass a callable to set_plain_auth. Clients keep using plain_username and plain_password. PLAIN does not encrypt traffic.

Performance

See COMPARISONS.md for full tables.

pyomq vs pyzmq performance

2-process loopback throughput and latency vs pyzmq, measured on Linux 6.12 (Debian 13), Intel i7-8700B 3.2 GHz, Rust 1.95.0.

zmq.proxy() forwarding (128 B, TCP)

pyomq pyzmq ratio
PUSH/PULL msg/s 3.04 M/s 1.57 M/s 1.94x
REQ/REP rt/s 7,484/s 4,348/s 1.72x

pyomq's proxy() forwards directly between sockets on the tokio runtime, no Python per-message overhead. pyzmq's zmq.proxy() calls libzmq's C-level zmq_proxy. PUSH/PULL forwarding is throughput-bound; REQ/REP proxy is latency-bound (4 TCP hops per round-trip).

Run scripts/update_perf.py (after maturin develop --release) to re-measure, regenerate the chart, and update the proxy table.

Compression transports

OMQ.rs adds transparent compression transports on top of TCP: lz4+tcp:// and experimental zstd+tcp://. Swap the scheme in your endpoint string and everything else stays the same:

push = ctx.socket(zmq.PUSH)
push.bind("lz4+tcp://127.0.0.1:5555")

pull = ctx.socket(zmq.PULL)
pull.connect("lz4+tcp://127.0.0.1:5555")

Both peers must use a matching compression endpoint. Payloads below the transport threshold are sent as-is when compression would not help.

Compression transports support static dictionaries and dictionary auto-training (off by default). Auto-training samples outbound messages, builds a 2 KiB dict, and ships it once per connection. Static dicts are set with compression_dict. zstd+tcp:// also accepts compression_level. Pure Rust (lz4rip / zrip), no C compiler required.

Enable it on sockets that send compressible traffic before bind()/connect():

push.compression_auto_train = 1
# or: push.setsockopt(zmq.OMQ_COMPRESSION_AUTO_TRAIN, 1)
push.compression_level = 1  # zstd+tcp only

See BENCHMARKS_COMPRESSION.md for throughput charts and benchmark details. Wire formats: LZ4, Zstd.

QUIC

quic:// carries reliable ZMTP messages over TLS 1.3. Check availability with pyomq.has("quic"). Set QUIC options before the socket's first bind/connect; later changes raise ZMQError. Sync and asyncio sockets use the same options.

from pathlib import Path

server = ctx.socket(pyomq.REP)
server.quic_cert_pem = Path("server.pem").read_bytes()
server.quic_key_pem = Path("server.key").read_bytes()
server.bind("quic://127.0.0.1:5555")

client = ctx.socket(pyomq.REQ)
client.quic_trust_system = 0
client.quic_trust_pem = Path("ca.pem").read_bytes()
client.quic_server_name = b"localhost"
client.connect("quic://127.0.0.1:5555")

System certificate roots are enabled by default. quic_server_name overrides the verified name; it does not disable verification. The optional quic_stream_window is a byte window (16 KiB to 256 MiB), not a message size limit. quic_max_ready_peers defaults to 1024. The corresponding OMQ_QUIC_* constants also work with setsockopt()/getsockopt().

Build the Rust test peer before running the cross-process tests:

cargo build -p omq-tokio --features quic --example quic_interop_peer
cd bindings/pyomq
OMQ_QUIC_INTEROP_REQUIRED=1 pytest tests/test_quic_interop.py

CURVE authentication

CURVE encrypts traffic and authenticates the server to the client. To also authenticate clients to the server, call set_curve_auth() before bind()/connect():

server_pub, server_sec = zmq.curve_keypair()
client_pub, client_sec = zmq.curve_keypair()

pull = ctx.socket(zmq.PULL)
pull.curve_server = 1
pull.curve_publickey = server_pub
pull.curve_secretkey = server_sec

# Option 1: allow specific client keys (checked in Rust, no GIL overhead)
pull.set_curve_auth([client_pub])

# Option 2: custom callback. PeerInfo has .public_key (Z85) and
# .identity (bytes or None).
pull.set_curve_auth(lambda peer: peer.public_key in allowed_keys)

# Option 3: accept any valid CURVE client (the default)
pull.set_curve_auth(None)

No ZAP, no filesystem key management. The callback runs during the CURVE handshake; returning a falsy value rejects the client.

On ROUTER and PEER, recv_from() returns an owning identity and all body frames; copy=False returns Frame objects, and the asyncio API is awaitable. The identity retains the admission snapshot across reconnects and socket closure; authentication contains verified facts, while diagnostics is for logging.

identity, frames = router.recv_from()
info = identity.peer_info
key = info.authentication.public_key  # raw CURVE key bytes, or None
endpoint = info.diagnostics.endpoint
router.send_to(identity, [b"reply"])  # route bytes may now select a replacement peer

Develop

cd bindings/pyomq
uv venv && source .venv/bin/activate
uv pip install maturin pyzmq pytest pytest-asyncio pytest-timeout
maturin develop --release
pytest -v

Metadata

Release files for pyomq 0.28.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for pyomq 0.28.1
File Size Uploaded Provenance Actions
pyomq-0.28.1.tar.gz 1.5 MB With provenance Details for pyomq-0.28.1.tar.gz

Built distributions (wheels)

Table of built distributions (wheels) for pyomq 0.28.1
File Actions
pyomq-0.28.1-cp312-abi3-win_arm64.whl CPython 3.12 abi3 Windows ARM64 Details for pyomq-0.28.1-cp312-abi3-win_arm64.whl
pyomq-0.28.1-cp312-abi3-win_amd64.whl CPython 3.12 abi3 Windows x86-64 Details for pyomq-0.28.1-cp312-abi3-win_amd64.whl
pyomq-0.28.1-cp312-abi3-musllinux_1_2_x86_64.whl CPython 3.12 abi3 Linux musl 1.2+ x86-64 Details for pyomq-0.28.1-cp312-abi3-musllinux_1_2_x86_64.whl
pyomq-0.28.1-cp312-abi3-musllinux_1_2_aarch64.whl CPython 3.12 abi3 Linux musl 1.2+ ARM64 Details for pyomq-0.28.1-cp312-abi3-musllinux_1_2_aarch64.whl
pyomq-0.28.1-cp312-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl CPython 3.12 abi3 Linux glibc 2.17+ x86-64 Details for pyomq-0.28.1-cp312-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl
pyomq-0.28.1-cp312-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl CPython 3.12 abi3 Linux glibc 2.17+ ARM64 Details for pyomq-0.28.1-cp312-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl
pyomq-0.28.1-cp312-abi3-macosx_11_0_arm64.whl CPython 3.12 abi3 macOS 11.0+ ARM64 Details for pyomq-0.28.1-cp312-abi3-macosx_11_0_arm64.whl
pyomq-0.28.1-cp312-abi3-macosx_10_12_x86_64.whl CPython 3.12 abi3 macOS 10.12+ x86-64 Details for pyomq-0.28.1-cp312-abi3-macosx_10_12_x86_64.whl

Total release size: 35.8 MB

Release files / pyomq-0.28.1.tar.gz

Download URL pyomq-0.28.1.tar.gz
Size 1.5 MB
Tags Source
SHA-256 checksum
How to use checksums
392a0d3b0f931be61df1798257059b569d230e9028dd054df698bcffbaa44b12
BLAKE2b-256 checksum
How to use checksums
2312ae2964a9c066d7eacd5ff93d49b72c5529ba43f78799f3595fab6cf9bcbb
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.

Transparency log

Release files / pyomq-0.28.1-cp312-abi3-win_arm64.whl

Download URL pyomq-0.28.1-cp312-abi3-win_arm64.whl
Size 4.0 MB
Tags CPython 3.12 Windows ARM64 abi3
SHA-256 checksum
How to use checksums
edb6ee557696c72901b1de22ee23b92ac01c6dafd79db9216fa92dbe4570ce66
BLAKE2b-256 checksum
How to use checksums
29089cf6da74784ab5b8f584c83189c281c3f4fba59151166ae816f0a4d98ea4
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.

Transparency log

Release files / pyomq-0.28.1-cp312-abi3-win_amd64.whl

Download URL pyomq-0.28.1-cp312-abi3-win_amd64.whl
Size 4.3 MB
Tags CPython 3.12 Windows x86-64 abi3
SHA-256 checksum
How to use checksums
29320a63c61ec6a6bfa1a6d5b7f90f89cff51f1f4c57b92f5eaee4968cf3cee3
BLAKE2b-256 checksum
How to use checksums
02b3eca79cf6d1be161a8454191f20a3d23bb3cfbd75c5cf740ade002f12552a
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.

Transparency log

Release files / pyomq-0.28.1-cp312-abi3-musllinux_1_2_x86_64.whl

Download URL pyomq-0.28.1-cp312-abi3-musllinux_1_2_x86_64.whl
Size 4.6 MB
Tags CPython 3.12 Linux musl 1.2+ x86-64 abi3
SHA-256 checksum
How to use checksums
8fdd7a62d1255d68cab3815f5f29c6c158b3875edbeb8d50b81b0c5739c86a78
BLAKE2b-256 checksum
How to use checksums
9f2647337a8eb92feb11150e4b0fdb9ce2084dc66e7b09b2dc1f562a41737be5
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.

Transparency log

Release files / pyomq-0.28.1-cp312-abi3-musllinux_1_2_aarch64.whl

Download URL pyomq-0.28.1-cp312-abi3-musllinux_1_2_aarch64.whl
Size 4.5 MB
Tags CPython 3.12 Linux musl 1.2+ ARM64 abi3
SHA-256 checksum
How to use checksums
928cd042050e9be4e427422dc590cde82d74d6de3b335e754f9c76a8d4138d94
BLAKE2b-256 checksum
How to use checksums
66f83224da7900bc13e9755ee1cd2a68d020847c25ba06f15fdb8e302017441d
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.

Transparency log

Release files / pyomq-0.28.1-cp312-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl

Download URL pyomq-0.28.1-cp312-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl
Size 4.4 MB
Tags CPython 3.12 Linux glibc 2.17+ x86-64 abi3
SHA-256 checksum
How to use checksums
0ad2494c52d0a3ad26e3541d6636941b79e6d34951b436e00da721c9694394e9
BLAKE2b-256 checksum
How to use checksums
0311dc06e538017a2986f9dbdd2197bbd7ca319125f05c071db449e04615725f
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.

Transparency log

Release files / pyomq-0.28.1-cp312-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl

Download URL pyomq-0.28.1-cp312-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl
Size 4.3 MB
Tags CPython 3.12 Linux glibc 2.17+ ARM64 abi3
SHA-256 checksum
How to use checksums
8d09703e4a01f33431ea40edef26404c3fbbe9abb8993aa6f1f6fa78d2a0b258
BLAKE2b-256 checksum
How to use checksums
7c5341b5ef356778ae42b962ad014c723c96161e11bfd7aa81d4b5721d0431e4
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.

Transparency log

Release files / pyomq-0.28.1-cp312-abi3-macosx_11_0_arm64.whl

Download URL pyomq-0.28.1-cp312-abi3-macosx_11_0_arm64.whl
Size 3.9 MB
Tags CPython 3.12 abi3 macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums
1db78f1b491dcac3456c8c94a8248a8a80856b434ad8bfd9cae3e245ac9c637c
BLAKE2b-256 checksum
How to use checksums
453045fbe4bf08f4fbdad6a56b78d2a42207ed4c8e2fa8ec4887e05da2fbf625
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.

Transparency log

Release files / pyomq-0.28.1-cp312-abi3-macosx_10_12_x86_64.whl

Download URL pyomq-0.28.1-cp312-abi3-macosx_10_12_x86_64.whl
Size 4.1 MB
Tags CPython 3.12 abi3 macOS 10.12+ x86-64
SHA-256 checksum
How to use checksums
2876ad67d3d4a5e63b52c7eea6ea445f235e177fd26650f1506ab3cf4b72302d
BLAKE2b-256 checksum
How to use checksums
303b3a0f1dee9dad65f54d110b8005e0390426f981cf9ba62ef39cd29d372e23
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.

Transparency log

Security for pyomq 0.28.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

All 9 files in this release have been uploaded with provenance metadata.

Select from 9 files

Attestation for pyomq-0.28.1.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.28.1 This release

9 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page