---
title: "paho-mqtt: Eclipse Paho MQTT Python Client"
library_name: paho-mqtt
pypi_package: paho-mqtt
category: networking
python_compatibility: "3.7+"
last_updated: "2025-11-02"
official_docs: "https://eclipse.dev/paho/files/paho.mqtt.python/html"
official_repository: "https://github.com/eclipse-paho/paho.mqtt.python"
maintenance_status: "active"
---

# paho-mqtt: Eclipse Paho MQTT Python Client

## Core Purpose

The model must state that paho-mqtt is the official Eclipse Foundation implementation of the MQTT protocol client for Python.

MQTT (Message Queuing Telemetry Transport) is a lightweight publish-subscribe messaging protocol designed for machine-to-machine (M2M) and Internet of Things (IoT) communication. The model must explain that paho-mqtt solves the problem of reliable, lightweight messaging in bandwidth-constrained or unreliable network environments.

### What Problem Does It Solve?

The model must identify these key use cases:

1. **IoT Device Communication**: Enables lightweight messaging between sensors, actuators, and control systems
2. **Publish-Subscribe Patterns**: Provides decoupled communication where publishers and subscribers do not need to know about each other
3. **Bandwidth-Constrained Networks**: Minimizes network overhead compared to HTTP/REST
4. **Unreliable Network Handling**: Built-in Quality of Service (QoS) levels ensure message delivery guarantees
5. **Bi-directional Communication**: Supports both sending commands to devices and receiving telemetry data

### Reinventing the Wheel Without It

The model must verify that without paho-mqtt, developers would need to:

- Implement the complex MQTT protocol specification from scratch @ <https://mqtt.org/mqtt-specification/>
- Handle connection management, keep-alive pings, and automatic reconnection logic
- Implement three QoS levels (0, 1, 2) with appropriate acknowledgment mechanisms
- Manage topic subscriptions and wildcard matching
- Handle TLS/SSL encryption and WebSocket transport layers

## Official Information

The model must cite these verified sources:

- **Official Repository**: <https://github.com/eclipse-paho/paho.mqtt.python> @ verified 2025-10-21
- **PyPI Package**: `paho-mqtt` @ <https://pypi.org/project/paho-mqtt/>
- **Official Documentation**: <https://eclipse.dev/paho/files/paho.mqtt.python/html/>
- **License**: EPL-2.0 OR BSD-3-Clause (Eclipse Distribution License v1.0 and Eclipse Public License 2.0)
- **Maintainer**: Eclipse Foundation @ <https://www.eclipse.org/paho/>
- **Latest Version**: 2.1.0 (as of 2025-10-21)
- **Status**: Active development, production-ready (Beta classification indicates mature but evolving API)

## Python Version Compatibility

The model must verify from pyproject.toml @ <https://github.com/eclipse-paho/paho.mqtt.python/blob/master/pyproject.toml>:

- **Minimum Python Version**: 3.7
- **Tested Versions**: 3.7, 3.8, 3.9, 3.10
- **Python 3.11-3.14 Status**: The model must state that Python 3.11+ compatibility is likely based on package maturity, but official classifiers only list up to 3.10. Users should test thoroughly.
- **Python 2.x**: NOT supported (users must stay on paho-mqtt 1.x for Python 2)

### Breaking Changes

The model must warn that version 2.0 introduced breaking changes:

- Callback API signatures changed (VERSION1 vs VERSION2)
- `CallbackAPIVersion` must now be explicitly specified
- Migration guide available @ <https://eclipse.dev/paho/files/paho.mqtt.python/html/migrations.html>

## Core Features

### 1. Quality of Service (QoS) Levels

The model must explain that MQTT provides three QoS levels @ <https://mqtt.org/mqtt-specification/>:

- **QoS 0 (At most once)**: Fire-and-forget, no acknowledgment, possible message loss
- **QoS 1 (At least once)**: Guaranteed delivery, possible duplicates, uses PUBACK
- **QoS 2 (Exactly once)**: Guaranteed single delivery, uses PUBREC/PUBREL/PUBCOMP handshake

Example from official docs @ <https://github.com/eclipse-paho/paho.mqtt.python/blob/master/README.rst>:

```python
import paho.mqtt.client as mqtt

# QoS 0: Fire and forget
client.publish("topic/sensor", "temperature:22", qos=0)

# QoS 1: At least once delivery
msg_info = client.publish("topic/critical", "alert", qos=1)
msg_info.wait_for_publish()  # Wait for PUBACK

# QoS 2: Exactly once delivery
client.publish("topic/transaction", "payment:100", qos=2)
```

### 2. Connection Management

The model must verify that paho-mqtt handles:

- **Keep-Alive Mechanism**: Automatic ping/pong to maintain connection
- **Automatic Reconnection**: Built-in retry logic with exponential backoff
- **Clean Session vs Persistent Session**: Control message persistence across disconnections
- **Last Will and Testament (LWT)**: Automatic message sent on unexpected disconnection

Example @ <https://eclipse.dev/paho/files/paho.mqtt.python/html/client.html>:

```python
import paho.mqtt.client as mqtt

def on_connect(client, userdata, flags, reason_code, properties):
    if reason_code.is_failure:
        print(f"Failed to connect: {reason_code}")
    else:
        print("Connected successfully")
        # Subscribe in on_connect ensures subscriptions persist across reconnections
        client.subscribe("sensors/#")

def on_disconnect(client, userdata, flags, reason_code, properties):
    if reason_code != 0:
        print(f"Unexpected disconnect: {reason_code}")

client = mqtt.Client(mqtt.CallbackAPIVersion.VERSION2)
client.on_connect = on_connect
client.on_disconnect = on_disconnect

# Configure reconnection with exponential backoff
client.reconnect_delay_set(min_delay=1, max_delay=120)

client.connect("mqtt.eclipseprojects.io", 1883, keepalive=60)
client.loop_forever()  # Handles automatic reconnection
```

### 3. Topic Wildcards

The model must explain MQTT topic wildcards @ <http://www.steves-internet-guide.com/understanding-mqtt-topics/>:

- **`+` (single-level wildcard)**: Matches one topic level, e.g., `home/+/temperature` matches `home/bedroom/temperature`
- **`#` (multi-level wildcard)**: Matches multiple levels, e.g., `sensors/#` matches `sensors/temp`, `sensors/humidity/outside`

```python
# Subscribe to all system topics
client.subscribe("$SYS/#")

# Subscribe to all rooms' temperature
client.subscribe("home/+/temperature")

# Helper function to check topic matches
from paho.mqtt.client import topic_matches_sub

assert topic_matches_sub("foo/#", "foo/bar")
assert topic_matches_sub("+/bar", "foo/bar")
assert not topic_matches_sub("non/+/+", "non/matching")
```

## Real-World Examples

The model must cite these verified examples from GitHub search @ 2025-10-21:

### 1. Home Assistant Integration

**Repository**: <https://github.com/home-assistant/core> (82,088 stars) **Use Case**: Open-source home automation platform using MQTT for device integration **Pattern**: Bidirectional communication with IoT devices (lights, sensors, thermostats)

```python
# Pattern extracted from Home Assistant ecosystem
import paho.mqtt.client as mqtt

def on_message(client, userdata, message):
    topic = message.topic  # e.g., "homeassistant/switch/living_room/state"
    payload = message.payload.decode()  # e.g., "ON" or "OFF"
    # Process device state changes
    handle_device_update(topic, payload)

client = mqtt.Client(mqtt.CallbackAPIVersion.VERSION2)
client.on_message = on_message
client.connect("homeassistant.local", 1883)
client.subscribe("homeassistant/#")
client.loop_forever()
```

### 2. AWS IoT Integration

**Repository**: <https://github.com/mariocannistra/python-paho-mqtt-for-aws-iot> (82 stars) **Use Case**: Connect Python applications to AWS IoT Core using MQTT over TLS **Pattern**: Secure cloud IoT communication with certificate-based authentication

```python
# Pattern from AWS IoT example @ https://github.com/mariocannistra/python-paho-mqtt-for-aws-iot
import paho.mqtt.client as mqtt
import ssl

client = mqtt.Client(mqtt.CallbackAPIVersion.VERSION2)

# AWS IoT requires TLS with client certificates
client.tls_set(
    ca_certs="root-CA.crt",
    certfile="device-cert.pem",
    keyfile="device-private.key",
    tls_version=ssl.PROTOCOL_TLSv1_2
)

# AWS IoT endpoint
client.connect("a1b2c3d4e5f6g7.iot.us-west-2.amazonaws.com", 8883)

# Publish sensor data
client.publish("device/telemetry", '{"temp": 22.5, "humidity": 65}', qos=1)
```

### 3. Async Wrapper Pattern

**Repository**: <https://github.com/mossblaser/aiomqtt> (53 stars) **Use Case**: AsyncIO wrapper around paho-mqtt for non-blocking event loops **Pattern**: Integration with modern Python async/await patterns

Note: The model must verify that paho-mqtt itself does NOT have native async support. Third-party wrappers exist:

- `aiomqtt` @ <https://github.com/empicano/aiomqtt> (recommended, actively maintained)
- `asyncio-mqtt` @ <https://github.com/sbtinstruments/asyncio-mqtt> (deprecated)

## Integration Patterns

### 1. MQTT Broker Compatibility

The model must verify that paho-mqtt works with these brokers @ <https://mqtt.org/software/>:

- **Eclipse Mosquitto**: Open-source, lightweight broker @ <https://mosquitto.org/>
- **HiveMQ**: Enterprise MQTT platform @ <https://www.hivemq.com/>
- **EMQX**: Scalable, distributed broker @ <https://www.emqx.io/>
- **AWS IoT Core**: Cloud-based managed service
- **Azure IoT Hub**: Microsoft cloud IoT platform
- **Google Cloud IoT Core**: Google cloud service

Example with Mosquitto @ <http://www.steves-internet-guide.com/into-mqtt-python-client/>:

```python
import paho.mqtt.client as mqtt

def on_message(client, userdata, message):
    print(f"Received: {message.payload.decode()} on {message.topic}")

client = mqtt.Client(mqtt.CallbackAPIVersion.VERSION2, client_id="python_client")
client.on_message = on_message

# Local Mosquitto broker
client.connect("localhost", 1883, 60)
client.subscribe("test/topic")
client.loop_forever()
```

### 2. WebSocket Transport

The model must verify WebSocket support @ <https://github.com/eclipse-paho/paho.mqtt.python/blob/master/ChangeLog.txt>:

```python
import paho.mqtt.client as mqtt

# Connect via WebSocket (useful for browser-based or proxy environments)
client = mqtt.Client(mqtt.CallbackAPIVersion.VERSION2, transport="websockets")

# Configure WebSocket path and headers
client.ws_set_options(path="/mqtt", headers={'User-Agent': 'Paho-Python'})

# Connect to broker's WebSocket port
client.connect("mqtt.example.com", 8080, 60)
```

### 3. TLS/SSL Encryption

The model must verify TLS support @ <https://eclipse.dev/paho/files/paho.mqtt.python/html/client.html>:

```python
import paho.mqtt.client as mqtt
import ssl

client = mqtt.Client(mqtt.CallbackAPIVersion.VERSION2)

# Server certificate validation
client.tls_set(
    ca_certs="ca.crt",
    certfile="client.crt",
    keyfile="client.key",
    tls_version=ssl.PROTOCOL_TLSv1_2
)

# For testing only: disable certificate verification (insecure!)
# client.tls_insecure_set(True)

client.connect("secure.mqtt.broker", 8883)
```

## Usage Examples

### Basic Publish

Example from official docs @ <https://github.com/eclipse-paho/paho.mqtt.python/blob/master/README.rst>:

```python
import paho.mqtt.publish as publish

# One-shot publish (connect, publish, disconnect)
publish.single(
    "home/temperature",
    payload="22.5",
    hostname="mqtt.eclipseprojects.io",
    port=1883
)

# Multiple messages at once
msgs = [
    {'topic': "sensor/temp", 'payload': "22.5"},
    {'topic': "sensor/humidity", 'payload': "65"},
    ('sensor/pressure', '1013', 0, False)  # Alternative tuple format
]
publish.multiple(msgs, hostname="mqtt.eclipseprojects.io")
```

### Basic Subscribe

Example from official docs @ <https://github.com/eclipse-paho/paho.mqtt.python/blob/master/README.rst>:

```python
import paho.mqtt.subscribe as subscribe

# Simple blocking subscribe (receives one message)
msg = subscribe.simple("home/temperature", hostname="mqtt.eclipseprojects.io")
print(f"{msg.topic}: {msg.payload.decode()}")

# Callback-based subscription
def on_message_handler(client, userdata, message):
    print(f"{message.topic}: {message.payload.decode()}")
    userdata["count"] += 1
    if userdata["count"] >= 10:
        client.disconnect()  # Stop after 10 messages

subscribe.callback(
    on_message_handler,
    "sensors/#",
    hostname="mqtt.eclipseprojects.io",
    userdata={"count": 0}
)
```

### Production-Grade Client

Example combining best practices @ <https://cedalo.com/blog/configuring-paho-mqtt-python-client-with-examples/>:

```python
import paho.mqtt.client as mqtt
import time

def on_connect(client, userdata, flags, reason_code, properties):
    if reason_code.is_failure:
        print(f"Connection failed: {reason_code}")
        return

    print(f"Connected with result code {reason_code}")
    # Subscribe in on_connect ensures subscriptions persist after reconnection
    client.subscribe("sensors/#", qos=1)

def on_disconnect(client, userdata, flags, reason_code, properties):
    if reason_code != 0:
        print(f"Unexpected disconnect. Reconnecting... (code: {reason_code})")

def on_message(client, userdata, message):
    print(f"Topic: {message.topic}")
    print(f"Payload: {message.payload.decode()}")
    print(f"QoS: {message.qos}")
    print(f"Retain: {message.retain}")

def on_publish(client, userdata, mid, reason_code, properties):
    print(f"Message {mid} published")

# Create client with VERSION2 callbacks (recommended)
client = mqtt.Client(
    mqtt.CallbackAPIVersion.VERSION2,
    client_id="sensor_monitor",
    clean_session=False  # Persistent session
)

# Set callbacks
client.on_connect = on_connect
client.on_disconnect = on_disconnect
client.on_message = on_message
client.on_publish = on_publish

# Authentication
client.username_pw_set("username", "password")

# TLS (if required)
# client.tls_set(ca_certs="ca.crt")

# Reconnection settings
client.reconnect_delay_set(min_delay=1, max_delay=120)

# Connect
client.connect("mqtt.example.com", 1883, keepalive=60)

# Start network loop in background thread
client.loop_start()

# Application logic
try:
    while True:
        # Publish sensor data
        result = client.publish("sensors/temperature", "22.5", qos=1)
        result.wait_for_publish()  # Block until published
        time.sleep(5)
except KeyboardInterrupt:
    print("Shutting down...")
finally:
    client.loop_stop()
    client.disconnect()
```

### Loop Management Patterns

The model must explain three loop options @ <https://eclipse.dev/paho/files/paho.mqtt.python/html/client.html>:

```python
import paho.mqtt.client as mqtt

client = mqtt.Client(mqtt.CallbackAPIVersion.VERSION2)
client.connect("mqtt.eclipseprojects.io", 1883)

# OPTION 1: Blocking loop (simplest)
# Runs forever, handles reconnection automatically
client.loop_forever()

# OPTION 2: Threaded loop (recommended for most cases)
# Runs in background thread, main thread free for other work
client.loop_start()
# ... do other work ...
client.loop_stop()

# OPTION 3: Manual loop (advanced, full control)
# Must be called regularly, manual reconnection handling
while True:
    rc = client.loop(timeout=1.0)
    if rc != 0:
        # Handle connection error
        break
```

## When NOT to Use paho-mqtt

The model must provide clear decision guidance based on verified constraints:

### Use HTTP/REST Instead When

1. **Request-Response Pattern**: Simple one-off queries without persistent connection
   - Example: Weather API calls, database queries
   - Reason: HTTP is simpler for synchronous request-response

2. **Large Payload Transfer**: Transferring files, images, or large datasets
   - Example: Uploading videos, downloading reports
   - Reason: HTTP has better tooling for chunked transfer, range requests

3. **Browser-Based Only**: Pure web applications without IoT integration
   - Example: Standard web app, SPA without real-time requirements
   - Reason: REST APIs are natively supported by browsers

4. **Strong Consistency Required**: Immediate consistency across all clients
   - Example: Financial transactions, inventory management
   - Reason: MQTT is eventually consistent, REST can enforce immediate consistency

### Use WebSockets Instead When

1. **Full-Duplex, Low-Latency Communication**: Real-time chat, gaming, collaborative editing
   - Example: Slack-like messaging, Google Docs collaboration
   - Reason: WebSockets provide bidirectional streams without MQTT protocol overhead

2. **Custom Protocol**: Need full control over message format and semantics
   - Example: Proprietary binary protocols, custom RPC
   - Reason: WebSockets are a transport layer, MQTT adds specific semantics

### Use Message Queues (RabbitMQ, Kafka) Instead When

1. **Complex Routing Logic**: Advanced routing rules, message transformation
   - Example: Enterprise service bus, workflow orchestration
   - Reason: RabbitMQ exchanges provide richer routing than MQTT topics

2. **High-Throughput Log Streaming**: Million+ messages per second, log aggregation
   - Example: Centralized logging, event sourcing at scale
   - Reason: Kafka optimized for high-throughput sequential writes

3. **Message Persistence and Replay**: Need to replay message history
   - Example: Event sourcing, audit trails
   - Reason: Kafka provides durable log storage, MQTT has limited persistence

## Decision Matrix: MQTT vs Alternatives

The model must provide this decision matrix based on verified use cases:

| **Use Case** | **MQTT (paho-mqtt)** | **HTTP/REST** | **WebSocket** | **Message Queue** |
| --- | --- | --- | --- | --- |
| **IoT Sensor Data** | ✅ Optimal | ❌ Too heavy | ⚠️ Possible | ❌ Overkill |
| **Home Automation** | ✅ Optimal | ❌ Polling inefficient | ⚠️ Possible | ❌ Too complex |
| **Mobile Notifications** | ✅ Good (battery efficient) | ⚠️ Polling wastes battery | ✅ Good | ❌ Overkill |
| **Real-time Chat** | ⚠️ Possible | ❌ No real-time | ✅ Optimal | ⚠️ Possible |
| **File Transfer** | ❌ Not designed for this | ✅ Better tools | ⚠️ Possible | ❌ Wrong tool |
| **Microservices RPC** | ⚠️ Possible | ✅ Standard approach | ❌ Overkill | ✅ Enterprise scale |
| **Telemetry Collection** | ✅ Optimal | ❌ Too chatty | ❌ Overkill | ✅ At massive scale |

### Use MQTT When

The model must verify these conditions favor MQTT:

1. ✅ **Bandwidth is constrained** (cellular, satellite links)
2. ✅ **Network is unreliable** (intermittent connectivity)
3. ✅ **Many-to-many communication** (pub-sub pattern)
4. ✅ **Low latency required** (< 100ms message delivery)
5. ✅ **Battery-powered devices** (minimal protocol overhead)
6. ✅ **IoT/M2M communication** (devices, sensors, actuators)
7. ✅ **Topic-based routing** (hierarchical topic namespaces)

### Use HTTP/REST When

The model must verify these conditions favor HTTP:

1. ✅ **Request-response pattern** (client initiates, server responds)
2. ✅ **Stateless interactions** (no persistent connection needed)
3. ✅ **Large payloads** (files, documents, media)
4. ✅ **Caching required** (HTTP caching semantics)
5. ✅ **Browser-based clients** (native browser support)
6. ✅ **Standard CRUD operations** (REST conventions)

### Use WebSocket When

The model must verify these conditions favor WebSocket:

1. ✅ **Full-duplex communication** (simultaneous send/receive)
2. ✅ **Custom protocol** (need full control over wire format)
3. ✅ **Browser-based real-time** (chat, collaboration, gaming)
4. ✅ **Lower latency than MQTT** (no protocol overhead)
5. ✅ **Simple point-to-point** (no pub-sub routing needed)

## Known Limitations

The model must cite these verified limitations @ <https://github.com/eclipse-paho/paho.mqtt.python/blob/master/README.rst>:

### Session Persistence

1. **Memory-Only Sessions**: When `clean_session=False`, session state is NOT persisted to disk
   - Impact: Session lost if Python process restarts
   - Lost data: QoS 2 messages in-flight, pending QoS 1/2 publishes
   - Mitigation: Use `wait_for_publish()` to ensure message delivery before shutdown

```python
# Session is only in memory!
client = mqtt.Client(mqtt.CallbackAPIVersion.VERSION2, clean_session=False)

# Ensure message is fully acknowledged before shutdown
msg_info = client.publish("critical/data", "important", qos=2)
msg_info.wait_for_publish()  # Blocks until PUBCOMP received
```

2. **QoS 2 Duplicate Risk**: With `clean_session=True`, QoS > 0 messages are republished after reconnection
   - Impact: QoS 2 messages may be received twice (non-compliant with MQTT spec)
   - Standard requires: Discard unacknowledged messages on reconnection
   - Recommendation: Use `clean_session=False` for exactly-once guarantees

### Native Async Support

The model must verify that paho-mqtt does NOT have native asyncio support:

- **Workaround**: Use third-party wrappers like `aiomqtt` @ <https://github.com/empicano/aiomqtt>
- **Alternative**: Use threaded loops (`loop_start()`) or external event loop support

```python
# NOT native async - need wrapper
import asyncio
from aiomqtt import Client  # Third-party wrapper

async def main():
    async with Client("mqtt.eclipseprojects.io") as client:
        async with client.messages() as messages:
            await client.subscribe("sensors/#")
            async for message in messages:
                print(message.payload.decode())

asyncio.run(main())
```

## Installation

The model must verify installation from official sources @ <https://pypi.org/project/paho-mqtt/>:

```bash
# Standard installation
pip install paho-mqtt

# With SOCKS proxy support
pip install paho-mqtt[proxy]

# Development installation from source
git clone https://github.com/eclipse-paho/paho.mqtt.python
cd paho.mqtt.python
pip install -e .
```

## Common Patterns and Best Practices

### 1. Reconnection Handling

The model must recommend this pattern @ <https://eclipse.dev/paho/files/paho.mqtt.python/html/client.html>:

```python
import paho.mqtt.client as mqtt

def on_connect(client, userdata, flags, reason_code, properties):
    # ALWAYS subscribe in on_connect callback
    # This ensures subscriptions are renewed after reconnection
    client.subscribe("sensors/#", qos=1)

def on_disconnect(client, userdata, flags, reason_code, properties):
    if reason_code != 0:
        print(f"Unexpected disconnect: {reason_code}")
        # loop_forever() and loop_start() will automatically reconnect

client = mqtt.Client(mqtt.CallbackAPIVersion.VERSION2)
client.on_connect = on_connect
client.on_disconnect = on_disconnect

# Configure reconnection delay
client.reconnect_delay_set(min_delay=1, max_delay=120)

client.connect("mqtt.example.com", 1883)
client.loop_forever()  # Handles reconnection automatically
```

### 2. Logging for Debugging

The model must recommend enabling logging @ <https://eclipse.dev/paho/files/paho.mqtt.python/html/client.html>:

```python
import logging
import paho.mqtt.client as mqtt

# Enable standard Python logging
logging.basicConfig(level=logging.DEBUG)

client = mqtt.Client(mqtt.CallbackAPIVersion.VERSION2)
client.enable_logger()  # Uses standard logging module

# Or use custom on_log callback
def on_log(client, userdata, level, buf):
    if level == mqtt.MQTT_LOG_ERR:
        print(f"ERROR: {buf}")

client.on_log = on_log
```

### 3. Graceful Shutdown

The model must recommend this pattern for clean disconnection:

```python
import paho.mqtt.client as mqtt
import signal
import sys

client = mqtt.Client(mqtt.CallbackAPIVersion.VERSION2)

def signal_handler(sig, frame):
    print("Shutting down gracefully...")
    client.disconnect()  # Triggers clean disconnect
    client.loop_stop()
    sys.exit(0)

signal.signal(signal.SIGINT, signal_handler)

client.connect("mqtt.example.com", 1883)
client.loop_start()

# Application runs...
signal.pause()  # Wait for SIGINT
```

## References and Sources

The model must cite these verified sources used in this research:

1. Official Eclipse Paho repository @ <https://github.com/eclipse-paho/paho.mqtt.python>
2. Official documentation @ <https://eclipse.dev/paho/files/paho.mqtt.python/html/>
3. MQTT specification @ <https://mqtt.org/mqtt-specification/>
4. Steve's Internet Guide (MQTT tutorials) @ <http://www.steves-internet-guide.com/>
5. HiveMQ MQTT client guide @ <https://www.hivemq.com/blog/mqtt-client-library-paho-python/>
6. Cedalo MQTT configuration guide @ <https://cedalo.com/blog/configuring-paho-mqtt-python-client-with-examples/>
7. EMQX Python MQTT guide @ <https://www.emqx.com/en/blog/how-to-use-mqtt-in-python>
8. Home Assistant core repository @ <https://github.com/home-assistant/core>
9. AWS IoT Python example @ <https://github.com/mariocannistra/python-paho-mqtt-for-aws-iot>
10. aiomqtt async wrapper @ <https://github.com/empicano/aiomqtt>

## Summary

The model must conclude that paho-mqtt is the recommended solution when:

1. Building IoT applications with resource-constrained devices
2. Implementing pub-sub messaging patterns with topic-based routing
3. Operating in unreliable or bandwidth-limited network environments
4. Requiring specific QoS guarantees for message delivery
5. Integrating with standard MQTT brokers (Mosquitto, HiveMQ, EMQX, AWS IoT)

The model must avoid paho-mqtt when:

1. Simple request-response patterns suffice (use HTTP/REST)
2. Real-time, low-latency browser communication needed (use WebSocket)
3. Complex message routing or high-throughput streaming required (use RabbitMQ/Kafka)
4. Large file transfers or binary data streaming needed (use HTTP)

The model must verify that paho-mqtt is production-ready, actively maintained by the Eclipse Foundation, and the de facto standard MQTT client library for Python.