PyWhales

PyWhales is a typed Python wrapper around the external Docker CLI. It builds docker command lines, runs them as subprocesses, and returns the results as Python objects. It isn't an HTTP SDK and doesn't call the Docker Engine API.

• Documentation
• GitHub repository

Requirements

• Python 3.14.10 or newer, on Linux, macOS or Windows.
• The Docker CLI, installed separately. See the Docker CLI guide.
• A reachable Docker daemon for commands that talk to it.
• The Compose and Buildx plugins for the commands that use them (docker.compose, docker.build).

Importing PyWhales or constructing a client doesn't check that the CLI, daemon or plugins are available. Problems show up when a command runs.

Install

uv pip install pywhales

Quickstart

from pywhales import docker

print(docker.run("hello-world", remove=True))
containers = docker.ps()
images = docker.image.list()

Building and Compose need local files: a Dockerfile for build (DockerClient.build is an alias for Buildx) and a Compose file for compose.

image = docker.build(".", tags="my-app:latest", load=True)
docker.compose.up(detach=True)

Custom configuration

docker is a shared default client. Create your own DockerClient to change its settings:

from pywhales import DockerClient

client = DockerClient(
    context="my-context",
    compose_files=["compose.yaml"],
    default_timeout=30,
)

The Docker context must already exist. default_timeout is in seconds and bounds each local CLI launch. Expiry kills and reaps the local CLI process, but doesn't roll back work the daemon has already started.

Good to know

• Containers, images, volumes and other resources are typed handles. Reading a property may inspect the resource and cache the result briefly. Call reload() when you want a fresh copy.
• Streaming calls that own a process return iterators. Close them, or use them as context managers, if you stop reading early.
• PYWHALES_DEBUG=1 turns on execution diagnostics that withhold command arguments, environment values and captured output. DockerClient(raw_diagnostics=True) opts a single client into raw diagnostics, so use it only where its logs are safe to expose.
• That redaction covers diagnostics only. Returned data, exception attributes and output PyWhales doesn't capture are not redacted.

More documentation

• Docker client and CLI setup
• docker.run() guide
• Exceptions
• Telemetry and diagnostics
• All user guides

License

PyWhales is released under the MIT license. See LICENSE.