{"id":1524,"library":"kazoo","title":"Kazoo","description":"Kazoo is a higher-level Python client for Apache ZooKeeper, providing robust abstractions for common distributed coordination tasks like locks, leader election, and queues. Version 2.11.0 is the latest stable release, with development active and releases occurring periodically, often driven by Python version support updates and bug fixes.","status":"active","version":"2.11.0","language":"python","source_language":"en","source_url":"https://github.com/python-zk/kazoo","tags":["zookeeper","distributed systems","coordination","async"],"install":[{"cmd":"pip install kazoo","lang":"bash","label":"Install stable version"}],"dependencies":[],"imports":[{"symbol":"KazooClient","correct":"from kazoo.client import KazooClient"},{"symbol":"KazooException","correct":"from kazoo.exceptions import KazooException"}],"quickstart":{"code":"import os\nimport time\nfrom kazoo.client import KazooClient\nfrom kazoo.exceptions import KazooException\n\n# Get Zookeeper host(s) from environment variable, e.g., '127.0.0.1:2181,127.0.0.1:2182'\nZOOKEEPER_HOSTS = os.environ.get('ZOOKEEPER_HOSTS', '127.0.0.1:2181')\n\nzk = KazooClient(hosts=ZOOKEEPER_HOSTS)\n\n@zk.add_listener\ndef my_listener(state):\n    \"\"\"Listener for Zookeeper connection state changes.\"\"\"\n    print(f\"Zookeeper state changed: {state}\")\n    if state == 'CONNECTED':\n        print(\"Successfully connected to Zookeeper!\")\n    elif state == 'LOST':\n        print(\"Connection to Zookeeper lost. Attempting to reconnect...\")\n    elif state == 'SUSPENDED':\n        print(\"Connection to Zookeeper suspended. Will attempt to reconnect.\")\n\ntry:\n    print(f\"Attempting to connect to Zookeeper at {ZOOKEEPER_HOSTS}...\")\n    zk.start()\n    zk.ensure_path(\"/my/kazoo/path\")\n    print(\"Created /my/kazoo/path if it didn't exist.\")\n\n    # Create an ephemeral node that will be deleted when the client disconnects\n    node_path = \"/my/kazoo/path/ephemeral_node\"\n    zk.create(node_path, b\"hello_kazoo\", ephemeral=True, sequence=False)\n    print(f\"Created ephemeral node: {node_path} with data 'hello_kazoo'\")\n\n    data, stat = zk.get(node_path)\n    print(f\"Retrieved data from {node_path}: {data.decode('utf-8')}, Stat: {stat}\")\n\n    # Keep the client alive for a few seconds to observe state changes or for other operations\n    time.sleep(5)\n\nexcept KazooException as e:\n    print(f\"A Kazoo-specific error occurred: {e}\")\nexcept Exception as e:\n    print(f\"An unexpected error occurred: {e}\")\nfinally:\n    if zk.connected:\n        zk.stop()\n        print(\"KazooClient stopped.\")\n    zk.close()\n    print(\"KazooClient closed.\")","lang":"python","description":"This quickstart demonstrates how to connect to Apache ZooKeeper using Kazoo, set up a connection state listener, create an ephemeral node, and retrieve its data. Remember to have a ZooKeeper instance running and set the `ZOOKEEPER_HOSTS` environment variable accordingly."},"warnings":[{"fix":"Refer to the latest Kazoo release notes or documentation for current Python compatibility. For example, Kazoo 2.10.0 dropped support for Python 3.7, now supporting Python 3.8-3.12.","message":"Kazoo frequently updates its supported Python versions, often dropping compatibility with older Python releases. Ensure your environment matches the supported versions to avoid compatibility issues.","severity":"breaking","affected_versions":"2.8.0+"},{"fix":"Implement a connection state listener using `@zk.add_listener` and structure your logic to react to connection events. Ensure `zk.start()` is called and the client has connected before attempting Zookeeper operations.","message":"KazooClient operates asynchronously. It's crucial to correctly manage the client's lifecycle (start, stop, close) and handle connection state changes (CONNECTED, SUSPENDED, LOST) using listeners or by checking `zk.connected` before performing operations. Operations performed while not connected can lead to errors or unexpected behavior.","severity":"gotcha","affected_versions":"all versions"},{"fix":"Always provide the Zookeeper host string in the correct `host:port,host:port` format. Validate the string if it's sourced from configuration or environment variables.","message":"The `hosts` parameter for `KazooClient` expects a comma-separated string of `host:port` pairs (e.g., '127.0.0.1:2181,127.0.0.2:2181'). Using spaces or other delimiters can lead to connection failures.","severity":"gotcha","affected_versions":"all versions"},{"fix":"Verify that the Zookeeper server (or ensemble) is running and accessible from the client's host and network on the configured port (default 2181). Check firewall rules, network connectivity, and ensure the Zookeeper service is active.","message":"KazooClient requires an active and accessible Zookeeper ensemble to establish a connection. Connection failures such as 'Connection refused' or 'Connection time-out' often indicate that the Zookeeper server is not running, is inaccessible due to network issues, or its firewall is blocking connections on the specified port.","severity":"gotcha","affected_versions":"all versions"},{"fix":"Ensure your Zookeeper server is running, accessible from the client's network, and configured to listen on the `host:port` provided to `KazooClient`. Verify network connectivity (e.g., using `telnet` or `nc`) to the Zookeeper server's address and port from the client's environment. Check Zookeeper server logs for binding or startup errors.","message":"KazooClient requires an active and accessible Zookeeper server to establish a connection. Errors like 'Connection refused' or 'Connection time-out' indicate that the client could not establish a network connection to the specified Zookeeper host and port, likely because the server is not running, not listening on the provided address/port, or is unreachable due to network configuration (e.g., firewall).","severity":"gotcha","affected_versions":"all versions"}],"env_vars":null,"search_vec":"'2.11.0':28 'abstract':15 'activ':36 'apach':11 'async':55 'bug':49 'client':9 'common':17 'coordin':19,54 'develop':35 'distribut':18,52 'driven':42 'elect':24 'fix':50 'higher':6 'higher-level':5 'kazoo':1,2 'latest':31 'leader':23 'level':7 'like':21 'lock':22 'occur':39 'often':41 'period':40 'provid':13 'python':8,44 'queue':26 'releas':33,38 'robust':14 'stabl':32 'support':46 'system':53 'task':20 'updat':47 'version':27,45 'zookeep':12,51","created_at":"2026-04-09T03:51:38.229865+00:00","updated_at":"2026-04-16T16:01:17.782776+00:00","problems":[{"fix":"pip install kazoo","cause":"The Kazoo library has not been installed in your Python environment.","error":"ModuleNotFoundError: No module named 'kazoo'"},{"fix":"Implement a connection listener to handle state changes (KazooState.SUSPENDED, KazooState.LOST, KazooState.CONNECTED) and consider using `kazoo.retry.KazooRetry` for operations that should be reattempted upon transient connection issues.","cause":"The Kazoo client lost its connection to the ZooKeeper server due to network issues, server unavailability, or session expiration.","error":"kazoo.exceptions.ConnectionLoss: Connection to the server has been lost."},{"fix":"Verify that the ZooKeeper server is running and accessible from the client. Consider increasing the `timeout` parameter during `KazooClient` initialization or in the `start()` method if network latency or server startup time is a factor.","cause":"The Kazoo client failed to establish or re-establish a connection to the ZooKeeper server within the configured timeout period during client startup or an operation.","error":"kazoo.handlers.threading.KazooTimeoutError: Connection time-out"},{"fix":"Ensure the node path is correct. If the node may or may not exist, use methods like `client.exists(path)` to check before operating, or `client.ensure_path(path)` to create parent nodes if missing before creating a child node.","cause":"You are attempting to perform an operation (e.g., get, set, delete) on a ZooKeeper node that does not exist at the specified path.","error":"kazoo.exceptions.NoNodeError: Node does not exist."},{"fix":"Ensure the correct `auth_data` (scheme and credentials) is provided to the `KazooClient` during initialization or added via `client.add_auth()` to match the ZooKeeper server's authentication requirements.","cause":"The authentication credentials provided to the Kazoo client are incorrect or the client is not authorized to perform operations on the ZooKeeper server.","error":"kazoo.exceptions.AuthFailedError: Client authentication failed."}],"ecosystem":"pypi","meta_description":null,"install_score":100,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"2.11.0","cli_name":"","cli_version":null,"type":"library","homepage":"https://kazoo.readthedocs.io","github":"https://github.com/python-zk/kazoo","docs":"https://kazoo.readthedocs.io","changelog":"https://github.com/python-zk/kazoo/releases","pypi":"https://pypi.org/project/kazoo/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["database","workflow"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-06-28","next_check":"2026-07-28","install_tag":"verified"}}