NewYour coding agent can read the release notes before it upgrades.Set up the MCP server →
PyPI
PyPI, #3437 most downloaded on PyPI
A simple Docker HTTP API wrapper written with asyncio and aiohttp.
Latest stable
0.27.0
Last release 5 months ago
27 May 2026
Ships unpredictably
gaps range from 9 days to 2.8 years
Most releases are documented
notes for 28 of 42 stable releases
Nothing withdrawn
no release was ever pulled
13 years old
47 releases · first in 2014
Drag across the ruler to compare, or tap a release to open it.
Vendor FlowControlDataQueue from aiohttp since it is deprecated and will be removed in aiohttp 4.0, and pin aiohttp<4.0 until the dependency is migrat…
images.push(), images.pull(), images.build(), and images.import_image() now raise DockerStreamError when the Docker Engine reports an error in the progress stream, instead of silently returning the error chunk as part of the response. Existing except DockerError blocks continue to catch these failures because DockerStreamError is a subclass. Callers that intentionally inspected the returned list for an error key must update their code to catch the exception instead. (#445)
images.pull() (and its Docker.pull alias) no longer triggers the Docker Engine's "pull all tags" behavior when tag is omitted and from_image has no embedded tag or digest; it now pulls "latest" instead. Callers that relied on the previous all-tags behavior must pass tag="" explicitly to opt back in. (#974)
Raise the minimum required aiohttp to >=3.11.13. Earlier releases contain a break inside a finally block in aiohttp/web_protocol.py which Python 3.14 turns into a SyntaxWarning under PEP 765; the offending code was fixed in aiohttp 3.11.13 (aio-libs/aiohttp#10434, backported in #10476). The 3.10 series is end-of-life. The CI test matrix now exercises aiohttp~=3.11.0 and aiohttp~=3.13.0 instead of 3.10 and 3.13. (#1038)
Fix DockerSwarm.join() so the request body is JSON-encoded. The endpoint previously sent a form-encoded body with a Content-Type: application/json header, causing the daemon to reject the request with a JSON decode error. (#288)
Raise DockerStreamError (a DockerError subclass) when the Docker Engine reports an error inside the JSON progress stream returned by images.push(), images.pull(), images.build(), and images.import_image(). Previously these calls returned HTTP 200 from the Engine even when the upstream registry rejected the operation (e.g. 403 Forbidden from Nexus or Docker Hub), and the error chunk was silently included in the returned list, giving callers no way to detect the failure. (#445)
Vendor FlowControlDataQueue from aiohttp since it is deprecated and will be removed in aiohttp 4.0, and pin aiohttp<4.0 until the dependency is migrated off the class. (#919)
Fix container membership check by renaming the misspelled __hasitem__ to __contains__ so the in operator works on DockerContainer instances. (#967)
Default images.pull() to the "latest" tag when neither a tag argument nor an embedded tag/digest in from_image is provided, matching the behavior of the docker pull CLI. (#974)
Fix the inverted condition in Stream.__del__ so a ResourceWarning is emitted when a stream is garbage-collected while still holding a live, unclosed response. (#1033)
Stop closing caller-supplied session and connector from Docker.close; only resources created internally are torn down, and Docker.close is now idempotent. (#1034)
Accept a typed filters mapping in DockerImages.list() (e.g. {"dangling": ["true"]}), matching the style of volumes.list(), networks.list(), and images.prune(). A pre-encoded JSON string is still accepted for backwards compatibility, but emits a DeprecationWarning and will be removed in 1.0. (#696)
Add DockerContainer.top to expose the containers/{id}/top API endpoint, accepting an optional ps_args argument. (#959)
Document how to bind-mount a host directory via HostConfig.Binds and HostConfig.Mounts, including bind-propagation options (shared, slave, etc.) and the host-side mount --make-shared prerequisite -- by achimnol. (#614)
Document docker.containers.list(all=True) for listing stopped containers, and note that any keyword argument is forwarded as a query parameter to the Docker Engine GET /containers/json endpoint -- by achimnol. (#831)
Replace a fixed five second sleep in the container log test helper with a follow stream read, so the helper waits only as long as the daemon takes to flush log output -- by bdraco. (#1020)
Replace a fixed ten second sleep in the non-TTY attach exit test with a wait for container exit, so the test returns as soon as the container actually finishes -- by bdraco. (#1023)
Build the distribution with uv build and run twine through uvx in CI, dropping the dedicated pip install steps for build and twine -- by bdraco. (#1026)
Replace legacy type annotations with Python3.10+ versions. (#1028)
Make uv the default development setup: track uv.lock in git, switch the Makefile, test.sh, and the README development docs to uv sync / uv run (with a pip-based fallback documented), and convert the CI lint and test jobs to use astral-sh/setup-uv with the matrix Python via UV_PYTHON_PREFERENCE=only-system. (#1038)
Your coding agent can read these notes before it upgrades. Set up the MCP server →
Introduce support in the library for the networks/prune API endpoint.
networks/prune API endpoint. (#691)images/prune API endpoint. (#1001)containers/prune API endpoint. (#1002)volumes/prune API endpoint. (#1003)build/prune API endpoint. (#1007)…the previous PRs #983 and #990; since this is a BREAKING CHANGE for those who have used the timeout argument for the DockerContainer.restart() method…
**kwargs with explicit parameters in DockerContainer.{stop,restart,kill,delete}() methods, accepting t for server-side stop timeout and timeout for client-side request timeouts for consistency with other methods covered in the previous PRs #983 and #990; since this is a BREAKING CHANGE for those who have used the timeout argument for the DockerContainer.restart() method calls, the users should replace it with t to keep the intended semantics (#991)X-Registry-Auth header would require URL-safe substitutions. (#941)~/.docker/contexts/ and respecting DOCKER_CONTEXT environment variable and SkipTLSVerify option. (#811)timeout configuration which becomes the base timeout configuration while still allowing legacy individual per-API timeouts and merging it into the base timeout. Now setting individual float (total) timeout per-API call is HIGHLY DISCOURAGED in favor of composable timeouts via stdlib's asyncio.timeout() async context manager. (#983)Added timeout parameter for push method
Introduce a sentinel value to _do_query() and its friend methods to allow configuring per-request infinite timeouts instead of always falling back to
_do_query() and its friend methods to allow configuring per-request infinite timeouts instead of always falling back to the session-level default timeout when setting the timeout argument to None, and add the timeout arguments to image-related API wrappers (#900)Use TYPE_CHECKING flag to avoid importing from typing_extensions at run time
TYPE_CHECKING flag to avoid importing from typing_extensions at run time (#876)Fix a missing removal of the legacy AsyncCM interface usage and update type annotations to avoid this in the future
AsyncCM interface usage and update type annotations to avoid this in the future (#874)Fixes unittests that don't run locally due to deprecations in later versions of Docker. Tested with 26.00, v1.45.
NOTICE: This release drops support for Python 3.7 and older. Please upgrade your Python version or keep using prior releases.
DockerVolume.delete() (#690)_AsyncCM to close when handling errors (#861)Starting container with non-empty request body was deprecated since API v1.22 and removed in v1.24
asyncio.run() pattern and initialize aiodocker.Docker() instance inside async functions where there is a valid running event loop (#837)Use ssl_context passed to Docker constructor for creating underlying connection to docker engine.
Use ssl_context passed to Docker constructor for creating underlying connection to docker engine. (#536)
Fix an error when attach/exec when container stops before close connection to it. (#608)
Accept auth parameter by run() method; it allows auto-pulling absent image from private storages.
Accept auth parameter by run() method; it allows auto-pulling absent image from private storages. (#295)
Fix passing of JSON params. (#543)
Fix issue with unclosed response object in attach/exec. (#604)
Fix type annotations for exec.start(), docker.images.pull(), docker.images.push(). Respect default arguments again.
Fix type annotations for exec.start(), docker.images.pull(), docker.images.push(). Respect default arguments again.
Run mypy checks on the repo in the non-strict mode.
Run mypy checks on the repo in the non-strict mode. (#466)
Add container.rename() method. (#458)
Changed DockerNetwork.delete() to return True if successful (#464)
Fix closing of the task fetching Docker's event stream and make it re-openable after closing
Fix closing of the task fetching Docker's event stream and make it re-openable after closing (#448)
Fix type annotations for pull() and push() methods. (#465)
#442
Don't send null for empty BODY.
Don't send null for empty BODY.
Bugfixes -------- - Fix some typing errors
Fix some typing errors
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Improve the error message when connection is closed by Docker Engine on TCP hijacking.
Improve the error message when connection is closed by Docker Engine on TCP hijacking. (#424)
Improve the error text message if cannot connect to docker engine.
Improve the error text message if cannot connect to docker engine. (#411)
Rename websocket() to attach() (#412)
Implement docker exec protocol. (#415)
Implement container commit, pause and unpause functionality. (#418)
Implement auto-versioning of the docker API by default. (#419)
Fix volume.delete throwing a TypeError. (#389)
Nothing published for this version
Fixed an issue when the entire tar archive was stored in RAM while building the image.
Fixed an issue when the entire tar archive was stored in RAM while building the image. (#352)
Nothing published for this version
Fix streaming mode for pull, push, build, stats and events.
Fix streaming mode for pull, push, build, stats and events. (#344)
Drop deprecated container.copy()
Add support for Docker 17.12.1 and 18.03.1 (#164)
Add initial support for nodes. (#181)
Add initial support for networks. (#189)
Add support for docker info ando docker swarm join. (#193)
Add restart method for containers. (#200)
Feature: Add support for registry-auth when you create a service. (#215)
Feature: Add support for docker save and load api methods (#219)
Pass params to docker events. (#223)
Add ability to get a Docker network by name or ID. (#279)
Always close response after processing, make .logs(..., follow=True) async iterator. (#341)
Fix: Set timeout for docker events to 0 (no timeout) (#115)
Fix: prevents multiple listener tasks to be created automatically (#116)
Fix: if container.start() fails user won't get the id of the container (#128)
Improve logging when docker socket not available. (#155)
Fix current project version. (#156)
Fix update out of sequence. (#169)
Remove asserts used to check auth with docker registry. (#172)
Fix: fix to parse response of docker load method as a json stream (#222)
Fix: Handle responses with 0 or missing Content-Length (#237)
Fix: don't remove non-newline whitespace from multiplexed lines (#246)
Fix docker_context.tar error (#253)
docker.images.get has been renamed to docker.images.inspect, remove support for Docker 17.06 (#164)
Drop Python 3.5 (#338)
Drop deprecated container.copy() (#339)
#28, #167, #192, #286
Nothing published for this version
Removal: docker.images.get has been renamed to docker.images.inspect, remove support for Docker 17.06
Feature: Add support for docker save and load api methods
Add support for registry-auth when you create a service.
Add initial support for networks.
Add support for docker info and docker swarm join
Remove asserts used to check auth with docker registry.
update out of sequence.Upgrade aiohttp version in base.txt. (#150) Refactor out scattered setting of content-type to "application/json" Fix: if container.start() fails user
Upgrade aiohttp version in base.txt. (#150) Refactor out scattered setting of content-type to "application/json" Fix: if container.start() fails user won't get the id of the container resolve errors and warnings (#125)
Fix: Set timeout for docker events to 0 (no timeout)
Fix: Set timeout for docker events to 0 (no timeout)
Fix: prevents multiple listener tasks to be created automatically
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
One column per quarter.