Kombu is an asynchronous messaging library for Python, providing a high-level interface to the AMQP protocol and supporting various message brokers. It abstracts away the complexities of message passing, allowing developers to focus on application logic. Currently at version 5.6.2, Kombu maintains an active development and release cadence, often aligning with updates in its parent project, Celery.
Install & Compatibility
Where this runs
tested against v5.6.2 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
76MB installed
● package 76MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Connection
✓ from kombu import Connection
Producer
✓ from kombu import Producer
Consumer
✓ from kombu import Consumer
Exchange
✓ from kombu import Exchange
Queue
✓ from kombu import Queue
QoS
✓ from kombu.common import QoS
eventloop
✓ from kombu.common import eventloop
This quickstart demonstrates the simple interface of Kombu to send and receive a message using a Redis broker. It creates a `SimpleQueue` for publishing and consuming, showcasing how to put a message and then retrieve it, acknowledging its receipt.
import datetime
from kombu import Connection
BROKER_URL = 'redis://localhost:6379/0' # Use os.environ.get('BROKER_URL', '...') in production
# --- Publisher ---
with Connection(BROKER_URL) as conn:
simple_queue = conn.SimpleQueue('simple_queue')
message_payload = f'helloworld, sent at {datetime.datetime.now()}'
simple_queue.put(message_payload)
print(f'Sent: {message_payload}')
simple_queue.close()
# --- Consumer ---
with Connection(BROKER_URL) as conn:
simple_queue = conn.SimpleQueue('simple_queue')
try:
message = simple_queue.get(block=True, timeout=5)
print(f'Received: {message.payload}')
message.ack()
except conn.Empty: # Or kombu.exceptions.TimeoutError
print('No messages received within timeout.')
finally:
simple_queue.close()
Debug
Known issues
breakingThe use of `datetime.datetime.utcnow()` is deprecated across Python and has been replaced with timezone-aware
`datetime.datetime.now(datetime.UTC)` in Kombu v5.6.0. Code using `utcnow()` might encounter deprecation warnings or unexpected behavior with
timezone handling.fixReplace `datetime.datetime.utcnow()` with `datetime.datetime.now(datetime.timezone.utc)` (Python 3.9+) or
`datetime.datetime.now(UTC)` if `from datetime import UTC` is used.
affects: >=5.6.0 (if still using `utcnow()`)
breakingKombu v5.5.4 introduced a change where `redis.connection.ConnectionPool.get_connection` no longer accepts arguments. This can
break applications using older `redis-py` versions or custom connection pool logic that passed arguments to this method.fixEnsure your `redis-py` dependency is compatible with Kombu's requirements and update any custom code that interacts directly with
`get_connection` without arguments.
affects: >=5.5.4
gotchaKombu v5.6.0 introduced the `max_prefetch` parameter for `kombu.common.QoS` to prevent Out Of Memory (OOM) crashes with queues
flooded by ETA/countdown tasks. By default, it's `None` (unlimited), which can still lead to OOM errors under heavy load.fixExplicitly set `max_prefetch` to a reasonable integer value (e.g., `100`) when initializing `kombu.common.QoS` if you handle many
tasks that might sit in memory.
affects: >=5.6.0
gotchaA `credential_provider` compatibility issue with `redis-py < 5.3.0` was fixed in Kombu v5.6.2. Users relying on
`credential_provider` with older `redis-py` versions might have experienced issues.fixUpgrade Kombu to 5.6.2 or later, and ensure your `redis-py` version is 5.3.0 or higher if using `credential_provider`.
affects: <5.6.2 (with `redis-py < 5.3.0`)
breakingAs of Kombu v5.6.0, MongoDB transport URI options are normalized to lowercase and flattened (e.g., `replicaSet=test_rs` becomes
`options['replicaset']`). This changes how options are accessed and might break existing configurations relying on case-sensitive or nested
structures.fixUpdate MongoDB transport configurations to use lowercase and flattened keys for URI options.
affects: >=5.6.0
breakingKombu v5.0.0 and subsequent v5.x releases require the `amqp` library version to be `>5.0`. Older versions of Kombu v5.0.x were
yanked from PyPI due to not enforcing this dependency correctly, leading to potential dependency conflicts and runtime errors.fixEnsure that `amqp` is installed at a version greater than 5.0 when using Kombu v5.x (e.g., `pip install 'kombu[amqp]'` or explicitly
`pip install amqp>=5.0`).
affects: >=5.0.0
gotchaWhen working with Kombu `Connection` objects, especially when using connection pools, it's best practice to use
`connection.release()` instead of `connection.close()`. `release()` returns the connection to the pool, while `close()` forcefully closes it,
potentially disrupting other parts of your application that expect the pool to manage connections.fixReplace `connection.close()` with `connection.release()` when finished with a connection obtained from a pool. Using `with
Connection(...) as conn:` is the most idiomatic way to ensure proper resource management.
affects: All v5.x
gotchaKombu removed Python 3.8 from CI as EOL in 5.6.0. Not officially dropped but untested going forward — silent failures possible
on 3.8.fixUpgrade to Python 3.9+ when using Kombu 5.6.x or later.
affects: >=5.6.0
breakingSQS transport switched from pycurl to urllib3 in 5.5.0, causing throughput to drop from ~100 tasks/sec to ~3/sec in some
environments, plus `UnknownOperationException` crash loops. Reverted in 5.6.2 — pycurl must be installed for SQS users on affected versions.fixUpgrade to Kombu 5.6.2+ or install pycurl explicitly if using SQS transport on affected versions.
affects: >=5.5.0, <5.6.2
gotchaNew `client_name` parameter added to Redis transport in 5.6.0. Without it, connections appear anonymous in Redis monitoring
tools — makes debugging harder in production.fixPass `client_name` in your Redis transport config to identify connections in monitoring tools.
affects: >=5.6.0
breakingCustom `LifoQueue` class conflicted with recent gevent versions in Kombu <5.6.0b3, causing silent failures in gevent-based
applications.fixUpgrade to Kombu 5.6.0b3 or later if using gevent.
affects: <5.6.0b3
gotchaBroker URLs with passwords were logged in plaintext by the delayed delivery mechanism in versions before 5.6.2.fixUpgrade to Kombu 5.6.2+ to prevent credential exposure in logs.
affects: <5.6.2
breakingKombu applications connecting to Redis will fail with `ConnectionRefusedError` if the Redis server is not running or is inaccessible at the specified host and port. This is an environmental issue and not a direct bug or breaking change within Kombu itself.fixEnsure the Redis server is running and accessible at the host and port specified in the Kombu connection URI (e.g., `redis://localhost:6379`). Verify network connectivity and Redis server status.
affects: All versions (if Redis is unavailable)
Errors
Common errors & fixes
AttributeError: 'Producer' object has no attribute 'send'
The 'send' method in the 'Producer' class has been deprecated and removed in recent versions of Kombu.
fixUse the 'publish' method instead: 'producer.publish(message, routing_key='queue_name')'.
ModuleNotFoundError: No module named 'kombu'
The Kombu library is not installed in the Python environment.
fixInstall Kombu using pip: 'pip install kombu'.
TypeError: 'Queue' object is not callable
Attempting to call a 'Queue' object as a function, which is not supported.
fixEnsure that the 'Queue' object is not being called as a function; check for any parentheses following the 'Queue' object.
ImportError: cannot import name 'Consumer' from 'kombu'
The 'Consumer' class has been moved or is not available in the current version of Kombu.
fixImport 'Consumer' from 'kombu.mixins': 'from kombu.mixins import Consumer'.
ValueError: No JSON object could be decoded
The message payload is not a valid JSON object.
fixEnsure that the message payload is properly formatted as a JSON object before sending.
Audit
Dependencies
amqprequiredCore dependency for AMQP transport. Kombu v5.x requires amqp > 5.0.
redisoptionalOptional: Enables Redis as a message broker.
librabbitmqoptionalOptional: C extension for AMQP, often faster than py-amqp.
boto3optionalOptional: Required for Amazon SQS transport (part of `sqs` extra).
pyyamloptionalOptional: Enables YAML serialization (part of `yaml` extra).
pymongooptionalOptional: Enables MongoDB as a message broker (part of `mongodb` extra).