{"id":4270,"library":"stomp-py","title":"stomp-py","description":"stomp.py is a Python client library for accessing messaging servers such as ActiveMQ, ActiveMQ Artemis, or RabbitMQ using the STOMP protocol (versions 1.0, 1.1, and 1.2). It provides both programmatic access and a command-line client for testing. The library, currently at version 8.2.0, adheres to semantic versioning and exclusively supports Python 3.x, having ended Python 2.x support in January 2020.","status":"active","version":"8.2.0","language":"en","source_language":"en","source_url":"https://github.com/jasonrbriggs/stomp.py","tags":["messaging","stomp","client","broker","activemq","rabbitmq","artemis"],"install":[{"cmd":"pip install stomp-py","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Requires Python 3.7 or newer, up to 3.x.","package":"python","optional":false},{"reason":"Dependency for command-line interface.","package":"docopt","optional":true},{"reason":"May be used for WebSocket STOMP connections.","package":"websocket-client","optional":true}],"imports":[{"note":"While Connection is in stomp.connect, the common and recommended import is directly from the top-level 'stomp' module for convenience.","wrong":"from stomp.connect import Connection","symbol":"Connection","correct":"import stomp\nconn = stomp.Connection()"},{"note":"Similar to Connection, ConnectionListener is commonly imported via the top-level 'stomp' module.","wrong":"from stomp.listener import ConnectionListener","symbol":"ConnectionListener","correct":"import stomp\nclass MyListener(stomp.ConnectionListener): ..."}],"quickstart":{"code":"import os\nimport time\nimport stomp\n\nclass MyListener(stomp.ConnectionListener):\n    def on_error(self, headers, body):\n        print(f'ERROR: {body}')\n\n    def on_message(self, headers, body):\n        print(f'MESSAGE: {body}')\n\nhost = os.environ.get('STOMP_HOST', 'localhost')\nport = int(os.environ.get('STOMP_PORT', '61613'))\nusername = os.environ.get('STOMP_USERNAME', 'guest')\npassword = os.environ.get('STOMP_PASSWORD', 'guest')\ndestination = os.environ.get('STOMP_DESTINATION', '/queue/test')\n\nhost_and_ports = [(host, port)]\n\ntry:\n    conn = stomp.Connection(host_and_ports)\n    conn.set_listener(MyListener())\n    conn.connect(username, password, wait=True, headers={'accept-version': '1.2', 'heart-beat': '10000,10000'})\n    print(f\"Connected to {host}:{port}\")\n\n    conn.subscribe(destination=destination, id=1, ack='auto')\n    print(f\"Subscribed to {destination}\")\n\n    print(f\"Sending message to {destination}\")\n    conn.send(body='Hello, STOMP!', destination=destination)\n\n    time.sleep(2) # Give time for message to be received\n\n    conn.disconnect()\n    print(\"Disconnected.\")\nexcept stomp.exception.ConnectFailedException as e:\n    print(f\"Failed to connect: {e}\")\nexcept Exception as e:\n    print(f\"An error occurred: {e}\")\n","lang":"python","description":"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."},"warnings":[{"fix":"Migrate your application to Python 3.7+ (current minimum requirement for stomp.py).","message":"stomp.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.","severity":"breaking","affected_versions":"4.2.0+"},{"fix":"Update 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.","message":"In 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.","severity":"breaking","affected_versions":"8.2.0+"},{"fix":"Ensure `set_ssl` is invoked after connection object creation but before starting the connection. Use `ssl.PROTOCOL_TLS` for SSL version parameter.","message":"When 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.","severity":"gotcha","affected_versions":"All versions supporting SSL"},{"fix":"Use `stomp.Connection12()` or pass `headers={'accept-version': '1.2'}` to `conn.connect()`.","message":"By 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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Configure 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.","message":"Persistent 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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure you `pip install stomp-py` and `import stomp`. Do not attempt to use or import the old single-file distribution.","message":"Older 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.","severity":"deprecated","affected_versions":"< 2.0.0"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}