Aiodocker

Warnings

• breaking 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.
  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.
• breaking 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`.
  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.
• breaking The method `docker.images.get` was renamed to `docker.images.inspect` and support for Docker API version 17.06 was removed in older versions.
  Fix: Update calls from `docker.images.get(...)` to `docker.images.inspect(...)`.
• gotcha 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.
  Fix: Catch `aiodocker.exceptions.DockerError` and check `if err.status == 404:` to specifically handle 'Not Found' errors.
• gotcha 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.
  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.

Install

• pip install aiodocker Install with pip

Imports

• Docker

  from aiodocker import Docker

• DockerError

  from aiodocker.exceptions import DockerError

  DockerError is part of the exceptions submodule, not directly under aiodocker.

Quickstart

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.

import asyncio
import aiodocker

async def list_and_run_containers():
    docker = aiodocker.Docker()
    try:
        print('== Images ==')
        for image in (await docker.images.list()):
            tags = image['RepoTags'][0] if image['RepoTags'] else ''
            print(image['Id'], tags)

        print('== Containers ==')
        for container in (await docker.containers.list()):
            print(f"  {container._id}")

        print('== Running a hello-world container ==')
        container = await docker.containers.create_or_replace(
            config={
                'Cmd': ['/bin/ash', '-c', 'echo "hello world"'],
                'Image': 'alpine:latest',
            },
            name='testing',
        )
        await container.start()
        logs = await container.log(stdout=True)
        print(''.join(logs))
        await container.delete(force=True)
    finally:
        await docker.close()

if __name__ == "__main__":
    asyncio.run(list_and_run_containers())