Install & Compatibility
Where this runs
tested against v2.11.1 · 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.915 runs
installs and imports cleanly · install 0.0s · import 0.110s · 22.8MB
glibcpy 3.10–3.915 runs
installs and imports cleanly · install 2.0s · import 0.101s · 23MB
21MB installed
● package 21MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Connection
✓ from amqpstorm import Connection
UriConnection
✓ from amqpstorm import UriConnection
Message
✓ from amqpstorm import Message
management
✓ from amqpstorm import management
Provides access to the Management API classes like ManagementApi.
This quickstart demonstrates how to establish a connection to RabbitMQ, open a channel, declare a queue, and publish a basic message using AMQPStorm. It uses environment variables for connection details and context managers for robust resource management.
import amqpstorm
import os
RABBITMQ_HOST = os.environ.get('RABBITMQ_HOST', 'localhost')
RABBITMQ_USER = os.environ.get('RABBITMQ_USER', 'guest')
RABBITMQ_PASS = os.environ.get('RABBITMQ_PASS', 'guest')
try:
# Establish a connection using a context manager for proper resource handling
with amqpstorm.Connection(RABBITMQ_HOST, RABBITMQ_USER, RABBITMQ_PASS) as connection:
# Open a channel using a context manager
with connection.channel() as channel:
# Declare a queue (idempotent operation)
channel.queue.declare('my_queue')
# Publish a simple message to 'my_queue'
channel.basic.publish(body='Hello, RabbitMQ!', routing_key='my_queue')
print(" [x] Sent 'Hello, RabbitMQ!'")
except amqpstorm.AMQPConnectionError as e:
print(f"Error connecting to RabbitMQ: {e}")
except Exception as e:
print(f"An unexpected error occurred: {e}")
Debug
Known issues
breakingStarting with version 2.0.0, messages are delivered as `Message` objects by default. Previous versions might have returned tuples or dictionaries directly from consumer functions.fixUpdate consumer logic to expect and interact with `amqpstorm.Message` objects. Access message content via `message.body` and properties via `message.properties` or `message.get_property('key')`. If necessary, explicitly set `to_tuple=True` or `to_dict=True` when consuming, but using `Message` objects is recommended. affects: >=2.0.0
gotchaThere's an open issue (#144) regarding `Import Error due to API Change in pamqp>=3.0.0 (specification -> commands)`, which is a core dependency. This might cause issues with newer `pamqp` versions.fixIf encountering `Import Error` related to `pamqp`, consider pinning your `pamqp` version to `<3.0.0` or checking the AMQPStorm GitHub issues for a resolution or newer AMQPStorm version that addresses this compatibility. `pip install 'pamqp<3.0.0'`
affects: >=2.11.0 with pamqp>=3.0.0
deprecatedThe library's `amqpstorm/message.py` currently uses `datetime.utcnow()`, which is deprecated in Python 3.12+ in favor of `datetime.now(timezone.utc)`. This is an open issue (#143).fixWhile this is an internal library usage, be aware that warnings might appear in Python 3.12+ environments. Keep an eye on AMQPStorm updates for a fix. No direct user-level fix is available, but it's generally harmless beyond the warning.
affects: Python 3.12+
gotchaProperly closing connections and channels is crucial to avoid resource leaks or hangs, especially in long-running applications or when handling errors.fixAlways use `with` statements (context managers) for `Connection` and `Channel` objects, as shown in the quickstart. This ensures resources are automatically released, even if errors occur. Explicitly call `connection.close()` and `channel.close()` if context managers are not used.
affects: All versions
gotchaWhen using SSL/TLS connections, incorrect `ssl_options` or `verify` parameter settings can lead to insecure connections (e.g., no certificate verification) or failed connections (e.g., incorrect CA bundles).fixCarefully configure `ssl_options` and `verify`. For production, always use `verify=True` (or provide a path to a CA bundle) and ensure `server_hostname` is correctly set. Only use `verify=False` for testing purposes where the risk is understood and mitigated.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'amqpstorm'
The 'amqpstorm' library is not installed in the Python environment.
fixInstall the library using pip: 'pip install amqpstorm'.
amqpstorm.exception.AMQPConnectionError: Connection timed out
The client is unable to establish a connection to the RabbitMQ server, possibly due to network issues or incorrect server details.
fixVerify the RabbitMQ server's hostname, port, and network connectivity; ensure the server is running and accessible.
amqpstorm.exception.AMQPConnectionError: (403) ACCESS_REFUSED - Login was refused using authentication mechanism PLAIN
The provided credentials are incorrect or the user lacks permission to access the RabbitMQ server.
fixCheck the username and password for accuracy and ensure the user has the necessary permissions on the RabbitMQ server.
amqpstorm.exception.AMQPChannelError: (404) NOT_FOUND - no exchange 'non_existent_exchange' in vhost '/'
The specified exchange does not exist in the RabbitMQ server.
fixCreate the exchange on the RabbitMQ server or verify the exchange name for correctness.
amqpstorm.exception.AMQPChannelError: (405) RESOURCE_LOCKED - cannot obtain exclusive access to locked queue 'my_queue' in vhost '/'
Attempting to access a queue that is locked or exclusively used by another connection.
fixEnsure no other connections are exclusively using the queue or declare the queue without the 'exclusive' flag.
Upgrade
Version history
3.1.4latest on PyPI · released Aug 4, 2026
Audit
Dependencies
requestsoptionalRequired for the Management API functionality.
amqpstorm-pooloptionalRequired for the connection pooling features.
pamqprequiredUnderlying AMQP 0-9-1 frame marshalling library (core dependency, usually installed automatically).