Install & Compatibility
Where this runs
tested against v9.0.0 · 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.152s · 19.1MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 2.2s · import 0.144s · 20MB
17MB installed
● package 17MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Connection
✓ import stomp
conn = stomp.Connection()
✗ from stomp.connect import Connection
While Connection is in stomp.connect, the common and recommended import is directly from the top-level 'stomp' module for convenience.
ConnectionListener
✓ import stomp
class MyListener(stomp.ConnectionListener): ...
✗ from stomp.listener import ConnectionListener
Similar to Connection, ConnectionListener is commonly imported via the top-level 'stomp' module.
This quickstart demonstrates how to establish a connection to a STOMP broker, register a listener to handle incoming messages, subscribe to a destination, send a message, and then disconnect. It uses environment variables for host, port, username, password, and destination, falling back to common defaults. It also explicitly sets STOMP protocol version 1.2 and heartbeats during connection.
import os
import time
import stomp
class MyListener(stomp.ConnectionListener):
def on_error(self, headers, body):
print(f'ERROR: {body}')
def on_message(self, headers, body):
print(f'MESSAGE: {body}')
host = os.environ.get('STOMP_HOST', 'localhost')
port = int(os.environ.get('STOMP_PORT', '61613'))
username = os.environ.get('STOMP_USERNAME', 'guest')
password = os.environ.get('STOMP_PASSWORD', 'guest')
destination = os.environ.get('STOMP_DESTINATION', '/queue/test')
host_and_ports = [(host, port)]
try:
conn = stomp.Connection(host_and_ports)
conn.set_listener(MyListener())
conn.connect(username, password, wait=True, headers={'accept-version': '1.2', 'heart-beat': '10000,10000'})
print(f"Connected to {host}:{port}")
conn.subscribe(destination=destination, id=1, ack='auto')
print(f"Subscribed to {destination}")
print(f"Sending message to {destination}")
conn.send(body='Hello, STOMP!', destination=destination)
time.sleep(2) # Give time for message to be received
conn.disconnect()
print("Disconnected.")
except stomp.exception.ConnectFailedException as e:
print(f"Failed to connect: {e}")
except Exception as e:
print(f"An error occurred: {e}")
stomp --version
Debug
Known issues
breakingstomp.py officially ended support for Python 2.x as of January 2020. All versions 4.2+ are Python 3.x only. Attempting to use newer versions with Python 2.x will result in compatibility errors.fixMigrate your application to Python 3.7+ (current minimum requirement for stomp.py).
affects: 4.2.0+
breakingIn version 8.2.0, the `stomp.__version__` attribute changed from a tuple to a string. Tools or scripts that parsed `stomp.__version__` as a tuple for version checks will break.fixUpdate any version parsing logic to expect a string, or use `stomp.get_version()` which returns a tuple, if available in the specific version being used.
affects: 8.2.0+
gotchaWhen configuring SSL, `conn.set_ssl()` must be called *before* `conn.start()`. Additionally, use `ssl.PROTOCOL_TLS` instead of deprecated version-specific protocols like `ssl.PROTOCOL_TLSv1_2` for broader compatibility.fixEnsure `set_ssl` is invoked after connection object creation but before starting the connection. Use `ssl.PROTOCOL_TLS` for SSL version parameter.
affects: All versions supporting SSL
gotchaBy default, `stomp.Connection()` might negotiate STOMP 1.1. If you explicitly require STOMP 1.2 features, it's recommended to use `stomp.Connection12()` or specify `headers={'accept-version': '1.2'}` in `conn.connect()` to ensure the correct protocol version is used.fixUse `stomp.Connection12()` or pass `headers={'accept-version': '1.2'}` to `conn.connect()`. affects: All versions
gotchaPersistent disconnections or connection failures can be caused by aggressive reconnection strategies or heartbeat timeouts. The default reconnection attempts (1 per second for 30 seconds) might be too short for some brokers.fixConfigure reconnection parameters like `reconnect_sleep_initial`, `reconnect_sleep_increase`, `reconnect_sleep_jitter` on the `stomp.Connection` object for a more robust exponential back-off strategy. Also, ensure appropriate heartbeat values (`heart-beat` header in `connect`) are set and handled correctly by both client and server.
affects: All versions
deprecatedOlder versions (prior to v2, circa 2013) of stomp.py were distributed as a single Python file (`stomp.py`). Modern versions are installed as a module. Direct imports of `stomp.py` as a file will fail.fixEnsure you `pip install stomp-py` and `import stomp`. Do not attempt to use or import the old single-file distribution.
affects: < 2.0.0
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'stomp'
The 'stomp.py' library is not installed in the Python environment being used.
fixInstall the library using pip: `pip install stomp.py`
TypeError: Connection.__init__() got an unexpected keyword argument 'host'
The `stomp.Connection` constructor does not accept 'host' and 'port' as direct keyword arguments; it expects a list of host-port tuples via the `host_and_ports` argument.
fixInitialize the connection with `host_and_ports`: `conn = stomp.Connection([('localhost', 61613)])` stomp.exception.ConnectFailedException: Unable to connect to any of the specified hosts
The STOMP client failed to establish a connection with any of the provided brokers, often because the broker is down, the host/port is incorrect, or network connectivity issues exist.
fixEnsure the STOMP broker is running, verify the `host_and_ports` configuration, and check network connectivity and firewall rules.
AttributeError: 'Connection' object has no attribute 'send_message'
The method for sending messages in `stomp.py` is named `send`, not `send_message`.
fixUse the correct method `send`: `conn.send(destination='/queue/test', body='Hello STOMP!')`
stomp.exception.NoHostsException: No hosts specified
The `stomp.Connection` constructor was called without providing any `host_and_ports` (e.g., an empty list or None), which is required to specify the broker's location.
fixProvide a non-empty list of host-port tuples: `conn = stomp.Connection([('localhost', 61613)])` Upgrade
Version history
9.0.0latest on PyPI · released May 12, 2026
Audit
Dependencies
pythonrequiredRequires Python 3.7 or newer, up to 3.x.
docoptoptionalDependency for command-line interface.
websocket-clientoptionalMay be used for WebSocket STOMP connections.