Skip to content

MQTTium documentation

MQTTium logo

MQTTium is a dependency-free, async-native MQTT 3.1.1 and MQTT 5 client for Python 3.11–3.14. It is built for production services, gateways, and connected devices that need explicit completion, bounded resource use, and reliable recovery.

Choose a path

  • Build a native client

    Install MQTTium and complete a publish/subscribe round trip with AsyncClient.

  • Prepare for production load

    Choose explicit limits in Configuration and Sizing, then use Operations and Observability to diagnose pressure.

  • Recover across failures

    Combine broker session retention, reconnect, and optional SQLite inflight state in Sessions and Persistence.

  • Migrate an existing client

    Move from Paho or gmqtt with the migration guide. The Paho VERSION2 facade is a Provisional transition surface, not the native API.

What the native client provides

Area Behaviour
Protocol MQTT 3.1.1 and MQTT 5; QoS 0, 1, and 2
Completion Per-message and aggregate receipts tied to MQTT semantics
Flow control Independent message and byte bounds for protocol, writer, ingress, and delivery state
Recovery Jittered reconnect, broker-session resumption, and optional persistent inflight state
Delivery Async iterator, synchronous or asynchronous callbacks, and manual acknowledgement
Transports TCP, TLS, WebSocket, and Unix-domain sockets
Operations Immutable snapshots and broker-negotiated limits without a background sampler
Packaging Typed Python package with no runtime dependencies

Start with Core Concepts for the completion, ownership, and backpressure model that distinguishes MQTTium from a minimal MQTT wrapper.

Documentation map

  • Guides solve application tasks: configuration, sessions, transports, MQTT 5, operations, troubleshooting, and complete recipes.
  • Reference records the Stable public imports, signatures, defaults, exceptions, compatibility tiers, and validated environments.
  • Concepts explain architecture, protocol ownership, conformance, and the no-library-logging decision.
  • Maintainer material defines benchmarking, fuzzing, stability, and release evidence requirements.
  • Historical evidence preserves dated reports without presenting their old measurements or conclusions as current behaviour.

API support tiers

The native entry points in mqttium, mqttium.api, and mqttium.helpers are the Stable public contract. Persistence, transports, protocol integrations, diagnostic snapshots, and Paho compatibility are Provisional. Implementation modules and underscore-prefixed objects are Internal.

See the API Stability Policy before depending on an advanced integration surface.

Trust and evidence

Protocol behaviour is checked with unit, integration, property, fuzz, memory, and broker-interoperability tests. Packaging checks install wheel and source artifacts in isolation. Performance claims require the reproducible controls in the Benchmarking Contract.

Current contracts live in the main documentation. Dated audits and campaign records live in the Historical Evidence index; report bodies are immutable records of the commit they name.