NewYour coding agent can read the release notes before it upgrades.Set up the MCP server →
PyPI · #1543 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.
More accurate error handling when streaming stdout and stderr by @Hasnainz in #703
docker compose up SERVICE --no-deps by @romeroyonatan in #708Full Changelog: v0.80.0...v0.81.0
feat: add support for buildx create --annotations flag by @bo0tzz in #690
--metadata-file option with buildx bake by @ianpittwood in #693Full Changelog: v0.79.0...v0.80.0
feat : Add support for Docker service networks in ComposeService by @R3gardless in #683
run by using @overload by @patrick91 in #685Thank you for your contributions! This makes me very happy to see new faces!
Full Changelog: v0.78.0...v0.79.0
Allow customization of --isolation and --quiet in legacy_build by @makuchma in #680
--isolation and --quiet in legacy_build by @makuchma in #680pull and push command by @dabico in #678Full Changelog: v0.77.0...v0.78.0
Rework filters to support passing multiple filters of the same type by @LewisGaul in #635
Full Changelog: v0.76.1...v0.77.0
Some breaking changes were introduced in this version. Those are rarely used features but it might impact you.
Some breaking changes were introduced in this version. Those are rarely used features but it might impact you.
python_on_whales.Builder:
my_builder.status -> my_builder.nodes[0].statusmy_builder.platforms -> my_builder.nodes[0].platformspython_on_whales.Secret:
my_secret.spec["name"] -> my_secret.spec.namemy_secret.spec["labels"] -> my_secret.spec.labelsFull Changelog: v0.75.1...v0.76.1
Work around setuptools license file metadata issue by @rcwbr in #666
Full Changelog: v0.75.0...v0.75.1
The python-on-whales command is not available anymore, meaning that you cannot download the docker client binary automatically. You need to install it
The python-on-whales command is not available anymore, meaning that you cannot download the docker client binary automatically.
You need to install it yourself by using the Docker installation guide: https://docs.docker.com/engine/install/ . Note that you need only the client, you can skip the installation of the full docker engine. For example, on Ubuntu, that means you just need to do
sudo apt-get install docker-ce-cli docker-buildx-plugin docker-compose-plugin
instead of
sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
ContainerCLI.create(env_files=path) by @LewisGaul in #637python-on-whales command by @gabrieldemarmiesse in #640defer_build=True pydantic config, improving import time significantly by @LewisGaul in #643is_infra and namespace fields to Container object by @LewisGaul in #641Full Changelog: v0.73.0...v0.74.0
🐛 Fix wrong links in docker_client.md by @gabrieldemarmiesse in #613
docker_client.md by @gabrieldemarmiesse in #613Full Changelog: v0.72.0...v0.73.0
Fix links in images objects docs. by @valberg in https://github.com/gabrieldemarmiesse/python-on-whales/pull/582
podman exec with --interactive and no --tty by @jhc4318 in https://github.com/gabrieldemarmiesse/python-on-whales/pull/583Full Changelog: https://github.com/gabrieldemarmiesse/python-on-whales/compare/v0.71.0...v0.72.0
Emit a DeprecationWarning when downloading the docker client by @LewisGaul in https://github.com/gabrieldemarmiesse/python-on-whales/pull/577
DockerClient.compose.config by @einarwar in https://github.com/gabrieldemarmiesse/python-on-whales/pull/572--wait-timeout option for docker.compose.up by @Taragolis in https://github.com/gabrieldemarmiesse/python-on-whales/pull/573DeprecationWarning when downloading the docker client by @LewisGaul in https://github.com/gabrieldemarmiesse/python-on-whales/pull/577--preserve-fds arg to container run/exec by @LewisGaul in https://github.com/gabrieldemarmiesse/python-on-whales/pull/576Full Changelog: https://github.com/gabrieldemarmiesse/python-on-whales/compare/v0.70.1...v0.71.0
fix repr return for Tasks by @anesmemisevic in https://github.com/gabrieldemarmiesse/python-on-whales/pull/565
Full Changelog: https://github.com/gabrieldemarmiesse/python-on-whales/compare/v0.70.0...v0.70.1
This update contains (hopefully) all fixes for the breaking changes introduced in docker compose v2.24.7. If you still encounter issues, file a issue…
This update contains (hopefully) all fixes for the breaking changes introduced in docker compose v2.24.7. If you still encounter issues, file a issue here and downgrade docker compose to v2.24.6 in the meantime.
detach_keys argument for start and exec by @jhc4318 in https://github.com/gabrieldemarmiesse/python-on-whales/pull/554podman.image.exists by @jhc4318 in https://github.com/gabrieldemarmiesse/python-on-whales/pull/558Full Changelog: https://github.com/gabrieldemarmiesse/python-on-whales/compare/v0.69.0...v0.70.0
Since this is a big release, I'll only put here the commits which have an impact on end users and remove internal refactoring.
Since this is a big release, I'll only put here the commits which have an impact on end users and remove internal refactoring.
client_type to add custom logic later by @gabrieldemarmiesse in https://github.com/gabrieldemarmiesse/python-on-whales/pull/524platforms parameter to buildx.create by @emalihin in https://github.com/gabrieldemarmiesse/python-on-whales/pull/541--env-host flag when creating containers by @LewisGaul in https://github.com/gabrieldemarmiesse/python-on-whales/pull/551Full Changelog: https://github.com/gabrieldemarmiesse/python-on-whales/compare/v0.68.0...v0.69.0
Error docker.execute with str by @kashyab12 in https://github.com/gabrieldemarmiesse/python-on-whales/pull/501
Full Changelog: https://github.com/gabrieldemarmiesse/python-on-whales/compare/v0.67.0...v0.68.0
This release is the first where we'll slowly force some arguments to be positional only or keyword only. This is to ensure we have the flexibility in
This release is the first where we'll slowly force some arguments to be positional only or keyword only. This is to ensure we have the flexibility in the future to change functions signatures without breaking people's code. Also that will make the user's code cleaner and less error prone.
If you get errors that look like "function xxxx take 2 positional arguments but recieved 4" then it's that we enforced the way to pass arguments. Double check the function signature in your documentation and IDE, it should be just a matter of specifying the argument name or not. Open an issue if you're having trouble.
In practice we don't expect much code to break, that seems unlikely.
If you're looking for some ressources:
Full Changelog: https://github.com/gabrieldemarmiesse/python-on-whales/compare/v0.66.0...v0.67.0
Fix doc deployment by @kashyab12 in https://github.com/gabrieldemarmiesse/python-on-whales/pull/489
Full Changelog: https://github.com/gabrieldemarmiesse/python-on-whales/compare/v0.65.0...v0.66.0
Expose dockerfile and args arguments under build by @jashparekh in https://github.com/gabrieldemarmiesse/python-on-whales/pull/477
This release is the first one that uses a pyproject.toml. This should silence the pip warning that some users might get.
Full Changelog: https://github.com/gabrieldemarmiesse/python-on-whales/compare/v0.64.3...v0.65.0
fix(ContainerConfig): stop-signal can be str or int by @ambasta in https://github.com/gabrieldemarmiesse/python-on-whales/pull/473
str or int by @ambasta in https://github.com/gabrieldemarmiesse/python-on-whales/pull/473Full Changelog: https://github.com/gabrieldemarmiesse/python-on-whales/compare/v0.64.2...v0.64.3
Remove deprecation warning when using pydantic V2 by @einarwar in https://github.com/gabrieldemarmiesse/python-on-whales/pull/469
Full Changelog: https://github.com/gabrieldemarmiesse/python-on-whales/compare/v0.64.1...v0.64.2
Expose DockerClient from the root of the package by @LewisGaul in https://github.com/gabrieldemarmiesse/python-on-whales/pull/462
DockerClient from the root of the package by @LewisGaul in https://github.com/gabrieldemarmiesse/python-on-whales/pull/462--systemd in container run/create by @LewisGaul in https://github.com/gabrieldemarmiesse/python-on-whales/pull/453Full Changelog: https://github.com/gabrieldemarmiesse/python-on-whales/compare/v0.64.0...v0.64.1
This is the first release to support pydantic v2. Pydantic v1 is still supported.
This is the first release to support pydantic v2. Pydantic v1 is still supported.
⚠️ pydantic v2.0.x will never be supported because of a datetime parsing bug in pydantic. Use pydantic 2.1 or above. ⚠️
Please file a bug if you encounter a Pydantic depreciation warning.
Full Changelog: https://github.com/gabrieldemarmiesse/python-on-whales/compare/v0.63.0...v0.64.0
456 use stdin to log in by @zimmdi in https://github.com/gabrieldemarmiesse/python-on-whales/pull/459
Full Changelog: https://github.com/gabrieldemarmiesse/python-on-whales/compare/v0.62.0...v0.63.0
Fix: fix the gh-pages ci by @kclamalex in https://github.com/gabrieldemarmiesse/python-on-whales/pull/449
Full Changelog: https://github.com/gabrieldemarmiesse/python-on-whales/compare/v0.61.0...v0.62.0
Installing this version requires python 3.8 or above. The end of life of python 3.7 is the 27 of june, so if you are still using it, please upgrade!
Installing this version requires python 3.8 or above. The end of life of python 3.7 is the 27 of june, so if you are still using it, please upgrade!
Full Changelog: https://github.com/gabrieldemarmiesse/python-on-whales/compare/v0.60.1...v0.61.0
:bug: Prevent the user from installing pydantic v2 by @gabrieldemarmiesse in https://github.com/gabrieldemarmiesse/python-on-whales/pull/430
⚠️ Install this release if you get the error AttributeError: type object 'NetworkIPAM' has no attribute '__fields__', see #429
Full Changelog: https://github.com/gabrieldemarmiesse/python-on-whales/compare/v0.60.0...v0.60.1
Add pull flag to docker compose up by @John-Vash in https://github.com/gabrieldemarmiesse/python-on-whales/pull/421
Full Changelog: https://github.com/gabrieldemarmiesse/python-on-whales/compare/v0.59.0...v0.60.0
⚠️ This release is the last one that supports Python 3.7. The version 0.61.0 will only support Python 3.8 and above
:wrench: Rework the CI by @gabrieldemarmiesse in https://github.com/gabrieldemarmiesse/python-on-whales/pull/414
Full Changelog: https://github.com/gabrieldemarmiesse/python-on-whales/compare/v0.58.0...v0.59.0
Add 'docker compose up --wait' functionality by @m-roberts in https://github.com/gabrieldemarmiesse/python-on-whales/pull/411
Full Changelog: https://github.com/gabrieldemarmiesse/python-on-whales/compare/v0.57.0...v0.58.0
Fix legacy build with podman when there is output on stderr by @LewisGaul in https://github.com/gabrieldemarmiesse/python-on-whales/pull/403
__all__ to specify what * should import from the main module by @rafrafek in https://github.com/gabrieldemarmiesse/python-on-whales/pull/397return_stderr should be True for run method to return tuple by @rafrafek in https://github.com/gabrieldemarmiesse/python-on-whales/pull/399None as Optional by @rafrafek in https://github.com/gabrieldemarmiesse/python-on-whales/pull/406Full Changelog: https://github.com/gabrieldemarmiesse/python-on-whales/compare/v0.56.0...v0.57.0
fix: Constrain the minimum bound of pydantic. by @DanCardin in https://github.com/gabrieldemarmiesse/python-on-whales/pull/389
Full Changelog: https://github.com/gabrieldemarmiesse/python-on-whales/compare/v0.55.0...v0.56.0
Implementing --pull flag for commands 'run' and 'create' and functions 'copy_from' and 'copy_to' (#369) by @MisterOwlPT in https://github.com/gabrield
Full Changelog: https://github.com/gabrieldemarmiesse/python-on-whales/compare/v0.54.0...v0.55.0
Implemented "attach" command. by @MisterOwlPT in https://github.com/gabrieldemarmiesse/python-on-whales/pull/371
manifest command by @raylas in https://github.com/gabrieldemarmiesse/python-on-whales/pull/378Full Changelog: https://github.com/gabrieldemarmiesse/python-on-whales/compare/v0.53.0...v0.54.0
:sparkles: Add a quiet option to docker.compose.down() by @gabrieldemarmiesse in https://github.com/gabrieldemarmiesse/python-on-whales/pull/365
Full Changelog: https://github.com/gabrieldemarmiesse/python-on-whales/compare/v0.52.0...v0.53.0
Add the quiet flag to docker.compose.pull() by @gabrieldemarmiesse in https://github.com/gabrieldemarmiesse/python-on-whales/pull/363
Full Changelog: https://github.com/gabrieldemarmiesse/python-on-whales/compare/v0.51.1...v0.52.0
Fix NetworkBindings parsing error by @betaboon in https://github.com/gabrieldemarmiesse/python-on-whales/pull/362
Full Changelog: https://github.com/gabrieldemarmiesse/python-on-whales/compare/v0.51.0...v0.51.1
Change behavior of empty list as argument to some functions by @gabrieldemarmiesse in https://github.com/gabrieldemarmiesse/python-on-whales/pull/352
Full Changelog: https://github.com/gabrieldemarmiesse/python-on-whales/compare/v0.50.0...v0.51.0
Fix image remove command by @LewisGaul in https://github.com/gabrieldemarmiesse/python-on-whales/pull/350
Full Changelog: https://github.com/gabrieldemarmiesse/python-on-whales/compare/v0.49...v0.50.0
Nothing published for this version
Allow to inspect exit_code and other info on exceptions by @juan-leon in https://github.com/gabrieldemarmiesse/python-on-whales/pull/342
Full Changelog: https://github.com/gabrieldemarmiesse/python-on-whales/compare/v0.47.0...v0.48.0
[FEAT] Add Event API by @lonk95 in https://github.com/gabrieldemarmiesse/python-on-whales/pull/340
Full Changelog: https://github.com/gabrieldemarmiesse/python-on-whales/compare/v0.46.0...v0.47.0
Handle custom registry name when using ecr login by @a-gentilhomme in https://github.com/gabrieldemarmiesse/python-on-whales/pull/338
Full Changelog: https://github.com/gabrieldemarmiesse/python-on-whales/compare/v0.45.0...v0.46.0
:bug: Fix parsing of a podman container by @gabrieldemarmiesse in https://github.com/gabrieldemarmiesse/python-on-whales/pull/336
Full Changelog: https://github.com/gabrieldemarmiesse/python-on-whales/compare/v0.44.0...v0.45.0
:sparkles: Added support for other clients like podman and nerdctl by @gabrieldemarmiesse in https://github.com/gabrieldemarmiesse/python-on-whales/pu
Full Changelog: https://github.com/gabrieldemarmiesse/python-on-whales/compare/v0.43.0...v0.44.0
Add more docker run examples in the readme by @gabrieldemarmiesse in https://github.com/gabrieldemarmiesse/python-on-whales/pull/325
Full Changelog: https://github.com/gabrieldemarmiesse/python-on-whales/compare/v0.42.0...v0.43.0
Force recent versions of typer by @gabrieldemarmiesse in https://github.com/gabrieldemarmiesse/python-on-whales/pull/320
Full Changelog: https://github.com/gabrieldemarmiesse/python-on-whales/compare/v0.41.0...v0.42.0
:bug: Fix bug with typer import crashing by @gabrieldemarmiesse in https://github.com/gabrieldemarmiesse/python-on-whales/pull/318
This will pink click to 8.0.4 and below. We'll make a new release later with an upgraded version of typer that doesn't have this issue.
Full Changelog: https://github.com/gabrieldemarmiesse/python-on-whales/compare/v0.40.0...v0.41.0
Add flags to docker compose pull by @joshkarlin in https://github.com/gabrieldemarmiesse/python-on-whales/pull/314
Full Changelog: https://github.com/gabrieldemarmiesse/python-on-whales/compare/v0.39.0...v0.40.0
capturing stdout and stderr for docker volume prune by @dvizzini in https://github.com/gabrieldemarmiesse/python-on-whales/pull/311
Full Changelog: https://github.com/gabrieldemarmiesse/python-on-whales/compare/v0.38.0...v0.39.0
Add project_urls by @wannaphong in https://github.com/gabrieldemarmiesse/python-on-whales/pull/309
Full Changelog: https://github.com/gabrieldemarmiesse/python-on-whales/compare/v0.37.0...v0.38.0
Fix system prune hang by @dvizzini in https://github.com/gabrieldemarmiesse/python-on-whales/pull/307
Full Changelog: https://github.com/gabrieldemarmiesse/python-on-whales/compare/v0.36.1...v0.37.0
:bug: Fix docker.service.list() when there are no services by @gabrieldemarmiesse in https://github.com/gabrieldemarmiesse/python-on-whales/pull/303
Full Changelog: https://github.com/gabrieldemarmiesse/python-on-whales/compare/v0.36.0...v0.36.1
:zap: Faster docker.service.list() by @gabrieldemarmiesse in https://github.com/gabrieldemarmiesse/python-on-whales/pull/301
Full Changelog: https://github.com/gabrieldemarmiesse/python-on-whales/compare/v0.35.0...v0.36.0
Some precisions concerning compose v2 in the docs by @gabrieldemarmiesse in https://github.com/gabrieldemarmiesse/python-on-whales/pull/296
Full Changelog: https://github.com/gabrieldemarmiesse/python-on-whales/compare/v0.34.0...v0.35.0
Fix typo 'lenght' in property names by @martinburchell in https://github.com/gabrieldemarmiesse/python-on-whales/pull/291
Full Changelog: https://github.com/gabrieldemarmiesse/python-on-whales/compare/v0.33.0...v0.34.0
Enable labeling networks in network create by @Akshay04 in https://github.com/gabrieldemarmiesse/python-on-whales/pull/284
Full Changelog: https://github.com/gabrieldemarmiesse/python-on-whales/compare/v0.32.0...v0.33.0
Added compose logs by @mdantonio in https://github.com/gabrieldemarmiesse/python-on-whales/pull/282
Full Changelog: https://github.com/gabrieldemarmiesse/python-on-whales/compare/v0.31.0...v0.32.0
Fixed compose.restart by adding services and made timeout parameter optional by @mdantonio in https://github.com/gabrieldemarmiesse/python-on-whales/p
Full Changelog: https://github.com/gabrieldemarmiesse/python-on-whales/compare/v0.30.0...v0.31.0
✨ Add docker.compose.restart() by @gabrieldemarmiesse in https://github.com/gabrieldemarmiesse/python-on-whales/pull/268
Full Changelog: https://github.com/gabrieldemarmiesse/python-on-whales/compare/v0.29.0...v0.30.0
Added the stream option to docker.execute() by @gabrieldemarmiesse in https://github.com/gabrieldemarmiesse/python-on-whales/pull/258
Full Changelog: https://github.com/gabrieldemarmiesse/python-on-whales/compare/v0.28.0...v0.29.0
Your coding agent can read these notes before it upgrades. Set up the MCP server →