{"id":2372,"library":"aiodocker","title":"Aiodocker","description":"Aiodocker is a Python library providing an asynchronous HTTP API wrapper for Docker, built upon `asyncio` and `aiohttp`. It allows programmatic interaction with Docker daemons from Python applications. Currently at version 0.26.0, the library is under active development with regular releases, ensuring compatibility with recent Docker API versions and Python features.","status":"active","version":"0.26.0","language":"en","source_language":"en","source_url":"https://github.com/aio-libs/aiodocker","tags":["docker","asyncio","aiohttp","container","api-client"],"install":[{"cmd":"pip install aiodocker","lang":"bash","label":"Install with pip"}],"dependencies":[{"reason":"Core dependency for asynchronous HTTP requests, minimum 3.10 since aiodocker 0.25.0.","package":"aiohttp","optional":false},{"reason":"Used for managing request timeouts, minimum 5.0 since aiodocker 0.25.0.","package":"async-timeout","optional":false}],"imports":[{"symbol":"Docker","correct":"from aiodocker import Docker"},{"note":"DockerError is part of the exceptions submodule, not directly under aiodocker.","wrong":"from aiodocker import DockerError","symbol":"DockerError","correct":"from aiodocker.exceptions import DockerError"}],"quickstart":{"code":"import asyncio\nimport aiodocker\n\nasync def list_and_run_containers():\n    docker = aiodocker.Docker()\n    try:\n        print('== Images ==')\n        for image in (await docker.images.list()):\n            tags = image['RepoTags'][0] if image['RepoTags'] else ''\n            print(image['Id'], tags)\n\n        print('== Containers ==')\n        for container in (await docker.containers.list()):\n            print(f\"  {container._id}\")\n\n        print('== Running a hello-world container ==')\n        container = await docker.containers.create_or_replace(\n            config={\n                'Cmd': ['/bin/ash', '-c', 'echo \"hello world\"'],\n                'Image': 'alpine:latest',\n            },\n            name='testing',\n        )\n        await container.start()\n        logs = await container.log(stdout=True)\n        print(''.join(logs))\n        await container.delete(force=True)\n    finally:\n        await docker.close()\n\nif __name__ == \"__main__\":\n    asyncio.run(list_and_run_containers())\n","lang":"python","description":"This quickstart demonstrates how to initialize the Docker client, list existing images and containers, run a 'hello-world' container, capture its logs, and then clean it up. It showcases basic asynchronous operations with the Docker API."},"warnings":[{"fix":"Upgrade Python to 3.10 or newer and ensure `aiohttp` >= 3.10 and `async-timeout` >= 5.0. Pin these versions in your project dependencies.","message":"Version 0.25.0 dropped support for Python 3.9. It now requires Python >= 3.10. Additionally, it updated minimum dependencies for `aiohttp` to 3.10 and `async-timeout` to 5.0.","severity":"breaking","affected_versions":"0.25.0 and later"},{"fix":"Review calls to these methods and replace `timeout=...` with `t=...` if you intended to set the server-side stop timeout. Use `timeout=...` for the client-side request timeout.","message":"In version 0.25.0, `DockerContainer.{stop, restart, kill, delete}()` methods replaced `**kwargs` with explicit parameters. Specifically, the server-side stop timeout is now `t` and the client-side request timeout is `timeout`. If you were passing `timeout` for server-side behavior, it must now be `t`.","severity":"breaking","affected_versions":"0.25.0 and later"},{"fix":"Update calls from `docker.images.get(...)` to `docker.images.inspect(...)`.","message":"The method `docker.images.get` was renamed to `docker.images.inspect` and support for Docker API version 17.06 was removed in older versions.","severity":"breaking","affected_versions":"0.15.0 and later (initial change), 0.25.0 and later (further cleanup)"},{"fix":"Catch `aiodocker.exceptions.DockerError` and check `if err.status == 404:` to specifically handle 'Not Found' errors.","message":"Unlike `docker-py`, `aiodocker` raises a generic `aiodocker.exceptions.DockerError` for 'Not Found' scenarios (e.g., image or container not existing). To check for a 'Not Found' error, you must inspect the `status` attribute of the exception.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Migrate from passing `timeout` as a float directly to API calls to using `asyncio.timeout()` for managing the overall execution time of your asynchronous operations.","message":"Setting individual float timeouts per-API call is highly discouraged starting from version 0.25.0. The recommended approach for managing timeouts is via Python's standard library `asyncio.timeout()` async context manager, for better composability and consistency.","severity":"gotcha","affected_versions":"0.25.0 and later"}],"env_vars":null,"last_verified":"2026-04-10T00:00:00.000Z","next_check":"2026-07-09T00:00:00.000Z"}