Kombu
raw JSON → 5.6.2 verified Tue May 12 auth: no python install: verified quickstart: stale
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.
pip install kombu Common errors
error AttributeError: 'Producer' object has no attribute 'send' ↓
cause The 'send' method in the 'Producer' class has been deprecated and removed in recent versions of Kombu.
fix
Use the 'publish' method instead: 'producer.publish(message, routing_key='queue_name')'.
error ModuleNotFoundError: No module named 'kombu' ↓
cause The Kombu library is not installed in the Python environment.
fix
Install Kombu using pip: 'pip install kombu'.
error TypeError: 'Queue' object is not callable ↓
cause Attempting to call a 'Queue' object as a function, which is not supported.
fix
Ensure that the 'Queue' object is not being called as a function; check for any parentheses following the 'Queue' object.
error ImportError: cannot import name 'Consumer' from 'kombu' ↓
cause The 'Consumer' class has been moved or is not available in the current version of Kombu.
fix
Import 'Consumer' from 'kombu.mixins': 'from kombu.mixins import Consumer'.
error ValueError: No JSON object could be decoded ↓
cause The message payload is not a valid JSON object.
fix
Ensure that the message payload is properly formatted as a JSON object before sending.
Warnings
breaking The 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. ↓
fix Replace `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.
breaking Kombu 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. ↓
fix Ensure your `redis-py` dependency is compatible with Kombu's requirements and update any custom code that interacts directly with
`get_connection` without arguments.
gotcha Kombu 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. ↓
fix Explicitly 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.
gotcha A `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. ↓
fix Upgrade Kombu to 5.6.2 or later, and ensure your `redis-py` version is 5.3.0 or higher if using `credential_provider`.
breaking As 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. ↓
fix Update MongoDB transport configurations to use lowercase and flattened keys for URI options.
breaking Kombu 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. ↓
fix Ensure 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`).
gotcha When 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. ↓
fix Replace `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.
gotcha Kombu 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. ↓
fix Upgrade to Python 3.9+ when using Kombu 5.6.x or later.
breaking SQS 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. ↓
fix Upgrade to Kombu 5.6.2+ or install pycurl explicitly if using SQS transport on affected versions.
gotcha New `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. ↓
fix Pass `client_name` in your Redis transport config to identify connections in monitoring tools.
breaking Custom `LifoQueue` class conflicted with recent gevent versions in Kombu <5.6.0b3, causing silent failures in gevent-based applications. ↓
fix Upgrade to Kombu 5.6.0b3 or later if using gevent.
gotcha Broker URLs with passwords were logged in plaintext by the delayed delivery mechanism in versions before 5.6.2. ↓
fix Upgrade to Kombu 5.6.2+ to prevent credential exposure in logs.
breaking Kombu 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. ↓
fix Ensure 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.
Install
pip install 'kombu[redis,librabbitmq,sqs,yaml]' Install compatibility verified last tested: 2026-05-12
python os / libc variant status wheel install import disk
3.10 alpine (musl) redis,librabbitmq,sqs,yaml build_error - - - -
3.10 alpine (musl) kombu wheel - 0.21s 23.6M
3.10 alpine (musl) redis,librabbitmq,sqs,yaml - - - -
3.10 alpine (musl) kombu - - 0.22s 23.4M
3.10 slim (glibc) redis,librabbitmq,sqs,yaml sdist 5.8s 0.14s 78M
3.10 slim (glibc) kombu wheel 2.0s 0.16s 24M
3.10 slim (glibc) redis,librabbitmq,sqs,yaml - - 0.13s 77M
3.10 slim (glibc) kombu - - 0.15s 24M
3.11 alpine (musl) redis,librabbitmq,sqs,yaml build_error - - - -
3.11 alpine (musl) kombu wheel - 0.29s 26.0M
3.11 alpine (musl) redis,librabbitmq,sqs,yaml - - - -
3.11 alpine (musl) kombu - - 0.32s 25.8M
3.11 slim (glibc) redis,librabbitmq,sqs,yaml wheel 4.7s 0.26s 80M
3.11 slim (glibc) kombu wheel 2.1s 0.27s 27M
3.11 slim (glibc) redis,librabbitmq,sqs,yaml - - 0.24s 79M
3.11 slim (glibc) kombu - - 0.24s 26M
3.12 alpine (musl) redis,librabbitmq,sqs,yaml build_error - - - -
3.12 alpine (musl) kombu wheel - 0.25s 17.8M
3.12 alpine (musl) redis,librabbitmq,sqs,yaml - - - -
3.12 alpine (musl) kombu - - 0.26s 17.6M
3.12 slim (glibc) redis,librabbitmq,sqs,yaml wheel 4.4s 0.30s 72M
3.12 slim (glibc) kombu wheel 1.9s 0.26s 18M
3.12 slim (glibc) redis,librabbitmq,sqs,yaml - - 0.26s 71M
3.12 slim (glibc) kombu - - 0.25s 18M
3.13 alpine (musl) redis,librabbitmq,sqs,yaml build_error - - - -
3.13 alpine (musl) kombu wheel - 0.26s 17.5M
3.13 alpine (musl) redis,librabbitmq,sqs,yaml - - - -
3.13 alpine (musl) kombu - - 0.25s 17.2M
3.13 slim (glibc) redis,librabbitmq,sqs,yaml wheel 4.1s 0.23s 72M
3.13 slim (glibc) kombu wheel 2.1s 0.24s 18M
3.13 slim (glibc) redis,librabbitmq,sqs,yaml - - 0.24s 70M
3.13 slim (glibc) kombu - - 0.24s 18M
3.9 alpine (musl) redis,librabbitmq,sqs,yaml build_error - - - -
3.9 alpine (musl) kombu wheel - 0.17s 23.1M
3.9 alpine (musl) redis,librabbitmq,sqs,yaml - - - -
3.9 alpine (musl) kombu - - 0.19s 22.9M
3.9 slim (glibc) redis,librabbitmq,sqs,yaml sdist 6.7s 0.18s 76M
3.9 slim (glibc) kombu wheel 2.3s 0.17s 24M
3.9 slim (glibc) redis,librabbitmq,sqs,yaml - - 0.15s 76M
3.9 slim (glibc) kombu - - 0.16s 23M
Imports
- 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
Quickstart stale last tested: 2026-04-24
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()