Reliable MQTT clients for Rust

Rumqttc-next provides asynchronous and synchronous MQTT clients with a small, explicit API and close control over connection behavior. It supports MQTT 3.1.1 and MQTT 5, TLS, WebSockets, proxies, tracking notice API, persistent sessions, manual acknowledgements, request and network-read batching, graceful disconnect, and reconnect handling.

This repository is an actively maintained fork of rumqttc, started in response to a period of upstream inactivity. It preserves the original project's focus on simplicity and performance while continuing protocol hardening, operational tooling, and API development independently.

See the migration and API differences guide for a practical comparison with upstream, and the changelog for the complete list of additions and fixes. Highlights include:

• separate, intentionally versioned MQTT 3.1.1 and MQTT 5 clients;
• client operations can be tracked to their actual protocol outcome;
• manual and customizable acknowledgements;
• stricter packet and protocol-state validation, backed by spec-compliance references;
• persistent session APIs, structured diagnostics, lifecycle tracing, and explicit reconnect, acknowledgement, and topic-alias policies;
• Configurable request and network-read batching, which can substantially improve throughput under sustained load;
• HTTP and SOCKS5 proxies, TLS backends, and WebSocket transports, and opt-in Linux Multipath TCP;
• updated dependencies to address vulnerabilities reported in RUSTSEC advisories.

Choose a client

Use case	Cargo package	Rust crate
MQTT 5 (recommended entry point)	rumqttc-next	rumqttc
MQTT 5 (explicit package)	rumqttc-v5-next	rumqttc
MQTT 3.1.1	rumqttc-v4-next	rumqttc

The *-next names are the packages published on crates.io; each library target is still named rumqttc, so application imports remain familiar.

cargo add rumqttc-next@0.34.0-alpha

use rumqttc::{AsyncClient, MqttOptions};

let options = MqttOptions::new("client-id", "localhost");
let (client, mut eventloop) = AsyncClient::builder(options).capacity(10).build();

Use rumqttc-v4-next in the command above for MQTT 3.1.1. For complete setup and usage, see the rumqttc-next, rumqttc-v5-next, and rumqttc-v4-next crate documentation.

Using both MQTT versions

The explicit v4 and v5 packages both expose a library target named rumqttc. When one crate depends on both packages, give each dependency a distinct name in Cargo.toml:

[dependencies]
rumqttc_v4 = { package = "rumqttc-v4-next", version = "0.34.0-alpha" }
rumqttc_v5 = { package = "rumqttc-v5-next", version = "0.34.0-alpha" }

The dependency names become the paths used by Rust code:

use rumqttc_v4::{AsyncClient as V4Client, MqttOptions as V4Options};
use rumqttc_v5::{AsyncClient as V5Client, MqttOptions as V5Options};

Without distinct dependency names, both library targets would claim the rumqttc extern-crate name in the same target.

Shared transport and codec code is published as rumqttc-core-next and mqttbytes-core-next. Standalone, no_std-capable packet codecs are published as mqttbytes-v4-next and mqttbytes-v5-next. Native wrapper infrastructure and the C API live in the independent native-wrappers workspace. Optional file-backed session stores live in the independent session-store-file workspace and do not add filesystem dependencies to the clients. Its protocol-neutral storage engine is maintained separately as atomic-blob-store.

Guides and ecosystem

The production recipes cover TLS, WebSockets, proxies, Notice API, persistent sessions, reconnect handling, bounded channels, manual ACKs, broker-specific configuration, and others.

Run clients using Docker

The checked-in Docker Compose example builds and runs finite MQTT 3.1.1 and MQTT 5 clients against a local Mosquitto broker:

docker compose -f docs/recipes/fixtures/docker-clients/compose.yaml up -d --wait broker
docker compose -f docs/recipes/fixtures/docker-clients/compose.yaml run --rm client-v4
docker compose -f docs/recipes/fixtures/docker-clients/compose.yaml run --rm client-v5
docker compose -f docs/recipes/fixtures/docker-clients/compose.yaml down -v

See the Docker client guide for the image layout, expected output, container networking, and production considerations.

Projects integrating this fork include mqtt-typed-client, a type-safe MQTT layer with an optional backend-rumqttc-next backend. See each package's crates.io page for current download and reverse-dependency data.

License

Licensed under the Apache License, Version 2.0.

Deliberate protocol interoperability exceptions are configured through each client's ProtocolCompatibility. MQTT 3.1.1 optionally accepts a broken clean Session Present response as a fresh session, preserving raw packet evidence and clearing old durable state before success. Defaults remain strict; MQTT 5 retains its existing broker-only session policy and restrictions. See the session recipes and diagnostics recipes.