============================== AsyncIO bindings for docker.io ==============================

.. image:: https://badge.fury.io/py/aiodocker.svg :target: https://badge.fury.io/py/aiodocker :alt: PyPI version

.. image:: https://img.shields.io/pypi/pyversions/aiodocker.svg :target: https://pypi.org/project/aiodocker/ :alt: Python Versions

.. image:: https://github.com/aio-libs/aiodocker/actions/workflows/ci-cd.yml/badge.svg?branch=main :target: https://github.com/aio-libs/aiodocker/actions/workflows/ci-cd.yml?query=branch%3Amain :alt: GitHub Actions status for the main branch

.. image:: https://codecov.io/gh/aio-libs/aiodocker/branch/main/graph/badge.svg :target: https://codecov.io/gh/aio-libs/aiodocker :alt: Code Coverage

.. image:: https://badges.gitter.im/Join%20Chat.svg :target: https://gitter.im/aio-libs/Lobby :alt: Chat on Gitter

A simple Docker HTTP API wrapper written with asyncio and aiohttp.

Installation ============

.. code-block:: sh

pip install aiodocker

Development ===========

The recommended developer setup uses uv <https://docs.astral.sh/uv/>_, which manages the virtualenv and resolves dependencies from the committed `uv.lock so every contributor and CI job builds against the same versions.

The Makefile helpers (make develop, make install, make lint, make test) all assume uv.

If you can't install uv, you can still bootstrap with pip. The resulting environment isn't pinned to uv.lock`, so versions may drift from CI.

.. code-block:: sh

python -m venv .venv && source .venv/bin/activate pip install -U pip pip install -e '.[dev,lint,test,doc]' # in zsh, you need to escape brackets pre-commit install

Running tests ~~~~~

.. code-block:: sh

# Run all tests make test

# Run individual tests uv run pytest tests/test_images.py

Building packages ~~~~~

NOTE: Usually you don't need to run this step by yourself.

.. code-block:: sh

uv build

Documentation =============

http://aiodocker.readthedocs.io

Examples ========

.. code-block:: python

import asyncio import aiodocker

async def list_things(docker): 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}")

async def run_container(docker): print('== Running a hello-world container ==') container = await docker.containers.createorreplace( 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)

async def main(): docker = aiodocker.Docker() await list_things(docker) await run_container(docker) await docker.close()

if name == "main": asyncio.run(main())