Install & Compatibility
Where this runs
tested against v1.4.4 · 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
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.280s · 19.2MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 1.6s · import 0.244s · 20MB
17MB installed
● package 17MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
BlockingConnection
✓ from pika import BlockingConnection
✗ from pika.blocking_connection import BlockingConnection
The BlockingConnection class is directly available under the pika namespace since version 1.0.0.
ConnectionParameters
✓ from pika import ConnectionParameters
PlainCredentials
✓ from pika import PlainCredentials
✗ from pika import credentials.PlainCredentials
PlainCredentials is available directly in the pika namespace since 1.0.0, and ConnectionParameters no longer accepts the credentials argument directly.
AsyncioConnection
✓ from pika.adapters.asyncio_connection import AsyncioConnection
Use the appropriate adapter for your asynchronous framework (e.g., asyncio, tornado).
This quickstart demonstrates a simple Pika producer using BlockingConnection to connect to a RabbitMQ instance (defaulting to localhost) and publish a message to a 'hello' queue. It also shows the basic setup for a consumer callback (commented out) and proper connection/channel closure.
import pika
import os
def callback(ch, method, properties, body):
print(f" [x] Received {body.decode()}")
# Get RabbitMQ host from environment or default to localhost
rabbitmq_host = os.environ.get('RABBITMQ_HOST', 'localhost')
connection = None
channel = None
try:
# Establish connection
connection = pika.BlockingConnection(pika.ConnectionParameters(host=rabbitmq_host))
channel = connection.channel()
# Declare a queue
channel.queue_declare(queue='hello')
# Publish a message
channel.basic_publish(exchange='', routing_key='hello', body='Hello World!')
print(" [x] Sent 'Hello World!'")
# Start consuming (example consumer setup)
# channel.basic_consume(queue='hello', on_message_callback=callback, auto_ack=True)
# print(' [*] Waiting for messages. To exit press CTRL+C')
# channel.start_consuming()
finally:
# Ensure channel and connection are closed
if channel and channel.is_open:
channel.close()
if connection and connection.is_open:
connection.close()
Debug
Known issues
breakingPika 1.0.0 introduced significant breaking changes, especially around connection parameters and callback signatures. `ConnectionParameters` no longer accepts `credentials` directly; `pika.PlainCredentials` (or similar) must be used. Also, the `on_message_callback` signature changed.fixFor `ConnectionParameters`, create a `pika.credentials.PlainCredentials` object and pass it via `pika.ConnectionParameters(credentials=...)`. Update `on_message_callback` to accept `(ch, method, properties, body)`.
affects: <1.0.0
gotchaMixing blocking (BlockingConnection) and non-blocking (AsyncioConnection, TornadoConnection) I/O models in the same application without proper isolation can lead to deadlocks, unexpected behavior, or resource exhaustion. Choose one I/O model and stick to it, or use separate processes for different models.fixEnsure you understand Pika's different I/O adapters. Use `BlockingConnection` for synchronous applications or scripts, and an appropriate `pika.adapters` class for asynchronous applications integrated with an event loop (e.g., `asyncio`, `Tornado`). Do not call blocking methods on a channel managed by an async adapter outside of its event loop.
affects: All versions
gotchaFailure to explicitly close channels and connections can lead to resource leaks (e.g., open file descriptors), hung processes, and issues with the RabbitMQ broker. Pika 1.0.0 and later require explicit closure for `BlockingConnection`.fixAlways ensure that `channel.close()` and `connection.close()` are called, typically in a `finally` block, after your AMQP operations are complete or when an exception occurs. For asynchronous adapters, the `stop()` method often handles this gracefully.
affects: All versions, especially >=1.0.0
gotchaPika does not automatically handle connection or channel recovery by default. Network outages, broker restarts, or protocol errors will cause `pika.exceptions.ConnectionClosed` or `pika.exceptions.ChannelClosed`.fixImplement robust error handling and reconnection logic in your application. For `BlockingConnection`, this typically involves a loop that attempts to re-establish the connection and channel after a delay. For asynchronous adapters, specific reconnection examples are often provided in the Pika documentation.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'pika'
The 'pika' library is not installed in the Python environment where the code is being executed, or the Python environment is not correctly configured.
fixRun `pip install pika` in your terminal to install the library. If using a virtual environment, ensure it is activated before installation.
pika.exceptions.AMQPConnectionError: Connection to localhost:5672 failed: [Errno 111] Connection refused
The application could not establish a TCP connection to the RabbitMQ server. This typically means the RabbitMQ server is not running, is listening on a different host/port, or a firewall is blocking the connection.
fixVerify that the RabbitMQ server is running and accessible from your application's host. Check the hostname and port in your Pika `ConnectionParameters` (default is 5672). Also, ensure no firewall rules are preventing the connection.
pika.exceptions.ProbableAccessDeniedError: ConnectionClosedByBroker: (403) 'ACCESS_REFUSED - Login was refused...'
The RabbitMQ broker rejected the client's connection attempt due to incorrect authentication credentials (username/password), insufficient user permissions, or the user not having access to the specified virtual host.
fixDouble-check the username, password, and virtual host used in your `pika.PlainCredentials` or `pika.URLParameters`. Ensure the RabbitMQ user exists and has the necessary permissions for the virtual host.
AttributeError: module 'pika' has no attribute 'BlockingConnection'
This usually happens when a Python file in your project or current directory is named 'pika.py', which shadows the actual installed 'pika' library. Python imports your local file instead of the library.
fixRename any Python files named 'pika.py' (or any other name that conflicts with pika's modules, like 'adapters.py') in your project directory to avoid shadowing the library.
pika.exceptions.StreamLostError: Stream connection lost: ConnectionResetError(104, 'Connection reset by peer')
The network connection to the RabbitMQ server was unexpectedly lost. This can be caused by network instability, the RabbitMQ server restarting, or a heartbeat timeout if the client or server failed to send heartbeats within the configured interval.
fixImplement robust connection and channel recovery logic in your application. Ensure that both Pika and RabbitMQ have appropriate heartbeat intervals configured. If using `BlockingConnection` with long-running tasks, periodically call `connection.process_data_events()` to allow Pika to process network events, including heartbeats.
Upgrade
Version history
1.4.4latest on PyPI · released Aug 6, 2026
Audit
Dependencies
No dependency data recorded yet.