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
77MB installed
● package 77MB
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.
Upgrade
Version history
5.6.2latest on PyPI · released Dec 29, 2025
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).