NewYour coding agent can read the release notes before it upgrades.Set up the MCP server →
PyPI · #1496 most downloaded on PyPI
A Docker client for Python, designed to be fun and intuitive!
Last release 6 months ago
09 Mar 2026
Ships on a steady schedule
a new release about every 2 months
Nearly every release is documented
notes for 59 of the last 60 stable releases
Nothing withdrawn
no release was ever pulled
6 years old
101 releases · first in 2020
One column per quarter.
Added docker.run(interactive=True, tty=True) by @dand-oss in https://github.com/gabrieldemarmiesse/python-on-whales/pull/256
docker container create/run --network-alias by @thomasleveil in https://github.com/gabrieldemarmiesse/python-on-whales/pull/257Full Changelog: https://github.com/gabrieldemarmiesse/python-on-whales/compare/v0.27.0...v0.28.0
Added docker.compose.down(volumes=True)
✨ Added more options for docker.compose.up()
Fix compose config bug, rc1 sets cpu as a string
Fix stack envfile parsing (#231) thanks @perewall !
Added a NotASwarmManager exception
Added a wrapper to make all fields in the pydantic models optional and allow None. This should reduce drastically the amount of surprises when parsing
python_on_whales.exceptions.NoSuchImagepython_on_whales.exceptions.NoSuchContainerpython_on_whales.exceptions.NoSuchServiceFixes docker.image.prune() hanging
docker.image.prune() hangingAdded --env-file compose option to ClientConfig
Fixed an issue where the typed file was not included.
Fixed an issue where the typed file was not included.
Added py.types (thanks @mdantonio !)
Add filters argument for docker.image.list() (#182) , thanks @haruishi43 !
Volume options have optional labels
Fixed the extra_hosts parsing error.
Add abort-on-container-exit option to compose.up
docker.login_ecr() now supports profile and respect various AWS environment variables, thanks @anouvel for the PR!
docker.login_ecr() now supports profile and respect various AWS environment variables, thanks @anouvel for the PR!docker.compose.stop() and docker.compose.rm()Added an option to log the commands used by setting the environment variable: PYTHON_ON_WHALES_DEBUG=1
PYTHON_ON_WHALES_DEBUG=1Fixed a bug where the environment variables were not propagated correctly.
When downloading buildx, use the version 0.5.1
When the Docker CLI is not installed, now the client 20.10.5 is downloaded instead of the 19.03.10.
Nothing published for this version
Fixed a bug that was triggered when parsing the system info output
Fixed a bug that was triggered when parsing the system info output
Fixed a bug occuring when pasing the response of the docker daemon for a task without the node id.
Better docs: A diagram was added.
Fixed a bug preventing the parsing of services.
Added multiple commands: * docker.compose.ps() * docker.swarm.unlock() * docker.swarm.unlock_key()
Added multiple commands:
docker.compose.ps()docker.swarm.unlock()docker.swarm.unlock_key()Fixed a bug that occured when parsing the volume json
docker.buildx.list()docker.node.ps()docker.stack.ps()docker.compose.push()docker.compose.pull()added some docker.plugin commands: inspect, list, remove...
docker.plugin commands: inspect, list, remove...Added some docker.context commands
docker.context commandsdocker.statsdocker.task.list() docker.task.inspect() docker.service.ps, docker.swarm.ca(), and added Tasks: python_on_whales.Task.docker.compose.up(), docker.compose.build(), docker.compose.down().Added a fix for certain services that could not be parsed. (CompletedAt not present)
Added a fix for certain services that could not be parsed. (CompletedAt not present)
Fixed the inspection of containers that were created with --volume-from #79
--volume-from #79docker.context -> docker.context.rm, docker.context.list, docker.context.inspect.Added docker.config functions and docs.
Added a lot more attributes and docs for Docker objects. This will help a lot users to write readable code and let their IDE guide them.
Added a lot more attributes and docs for Docker objects. This will help a lot users to write readable code and let their IDE guide them.
One possible downside is that the parsing of the json is stricter now. If you encounter a parsing issue with pydantic, just open an issue and it'll be fixed very quickly. Parsing errors are very easy to fix. Most of the time, it's just needed to add Optional[xxx] to solve the problem.
Added initial support for docker compose (the go version, not the python one).
A lot of new buildx commands are now available, especially concerning the builders.
return_image in docker.build() since python on whales can infer if an image will be loaded.output option of docker.build()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
Your coding agent can read these notes before it upgrades. Set up the MCP server →