{"id":5012,"library":"py-consul","title":"py-consul: Python Client for Consul","description":"py-consul is an actively maintained Python client for Hashicorp Consul, enabling interaction with its Key/Value store, service discovery, health checks, and ACLs. It provides both synchronous and asynchronous (asyncio-based) interfaces. The library is currently at version 1.7.1 and releases occur periodically to address bug fixes, introduce new features, and maintain compatibility with newer Python and Consul versions.","status":"active","version":"1.7.1","language":"en","source_language":"en","source_url":"https://github.com/criteo/py-consul","tags":["consul","hashicorp","service discovery","kv store","configuration management","asyncio"],"install":[{"cmd":"pip install py-consul","lang":"bash","label":"Standard Install"}],"dependencies":[{"reason":"Required for the `consul.aio` (asyncio) client.","package":"aiohttp","optional":true}],"imports":[{"note":"While 'import consul' works, 'from consul import Consul' is the idiomatic way to import the main client class.","wrong":"import consul; client = consul.Consul()","symbol":"Consul","correct":"from consul import Consul"},{"note":"The recommended pattern for the async client is to import the 'aio' module and instantiate 'aio.Consul()', as shown in official examples.","wrong":"from consul.aio import Consul","symbol":"aio","correct":"from consul import aio"}],"quickstart":{"code":"import consul\nimport os\n\n# Configure Consul client (defaults to localhost:8500)\n# Use environment variable CONSUL_HTTP_ADDR for production setup\nconsul_host = os.environ.get('CONSUL_HTTP_ADDR', '127.0.0.1')\nconsul_port = int(os.environ.get('CONSUL_HTTP_PORT', '8500'))\nconsul_token = os.environ.get('CONSUL_HTTP_TOKEN', None)\n\nc = consul.Consul(host=consul_host, port=consul_port, token=consul_token)\n\n# --- Key-Value Store Operations ---\n\n# 1. Put a key-value pair\nsuccess = c.kv.put('my-app/config/greeting', 'Hello, Consul!')\nif success:\n    print(\"Key 'my-app/config/greeting' set successfully.\")\n\n# 2. Get a key-value pair\nindex, data = c.kv.get('my-app/config/greeting')\nif data:\n    value = data['Value'].decode('utf-8') # Value is bytes, needs decoding\n    print(f\"Retrieved key: {data['Key']}, Value: {value}, ModifyIndex: {data['ModifyIndex']}\")\nelse:\n    print(\"Key 'my-app/config/greeting' not found.\")\n\n# 3. List keys under a prefix\nindex, keys = c.kv.get('my-app/config/', recurse=True)\nif keys:\n    print(\"\\nKeys under 'my-app/config/':\")\n    for item in keys:\n        key = item['Key']\n        value = item['Value'].decode('utf-8') if item['Value'] else None\n        print(f\"  - {key}: {value}\")\nelse:\n    print(\"\\nNo keys found under 'my-app/config/'.\")\n\n# --- Service Registration (Agent API) ---\n# This requires a running Consul agent\n# try:\n#     c.agent.service.register(\n#         'my-service',\n#         service_id='my-service-1',\n#         address='127.0.0.1',\n#         port=8000,\n#         tags=['web', 'python'],\n#         check=consul.check.HTTP('http://127.0.0.1:8000/health', interval='10s')\n#     )\n#     print(\"\\nService 'my-service-1' registered.\")\n# except Exception as e:\n#     print(f\"\\nFailed to register service: {e}\")\n","lang":"python","description":"This quickstart demonstrates how to initialize the `py-consul` client and perform basic Key/Value store operations such as setting, retrieving, and listing entries. It also includes an example of service registration using the agent API (commented out by default) and shows how to handle Consul's byte string values."},"warnings":[{"fix":"Upgrade your Python environment to 3.10 or newer. If you must use an older Python, pin `py-consul` to `<1.7.0` (e.g., `py-consul<1.7`).","message":"Python 3.8 and older versions are no longer supported. Version 1.7.0 and later explicitly require Python 3.10 or higher.","severity":"breaking","affected_versions":">=1.7.0"},{"fix":"Update your code to use `client.acl.token` for ACL operations instead of `client.acl`. For example, `c.acl.token.create()` instead of `c.acl.create()`.","message":"The ACL endpoint was moved from `consul.acl` to `consul.acl.token` in version 1.5.0, aligning with upstream Consul API changes.","severity":"breaking","affected_versions":">=1.5.0"},{"fix":"Always decode the `Value` field from the dictionary returned by `c.kv.get()` and `c.kv.get(recurse=True)`. Example: `data['Value'].decode('utf-8')`.","message":"Values retrieved from Consul's Key/Value store are always returned as byte strings. Failing to decode them (e.g., using `.decode('utf-8')`) can lead to unexpected `TypeError` or incorrect data handling.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-12T00:00:00.000Z","next_check":"2026-07-11T00:00:00.000Z"}