python-on-whales

0.81.0 · active · verified Thu Apr 09

python-on-whales is an intuitive Python client for interacting with Docker, Docker Compose, and Docker Buildx, designed to be fun and intuitive. It simplifies running Docker commands from Python scripts, providing a fluent API. The library is currently at version 0.81.0 and releases updates frequently, often on a monthly or bi-monthly cadence.

Warnings

breaking The `python-on-whales` command-line utility, which could automatically download the Docker client binary, was removed in `v0.74.0`. Users must now manually install the Docker CLI (e.g., `docker-ce-cli`, `docker-buildx-plugin`, `docker-compose-plugin`) for `python-on-whales` to function.
Fix: Install the Docker CLI manually using official Docker documentation for your operating system. For example, on Ubuntu: `sudo apt-get install docker-ce-cli docker-buildx-plugin docker-compose-plugin`.
breaking The API for `docker.secret.create()` changed in `v0.76.1`. It now returns a `Secret` object instead of an integer ID, and the `labels` argument expects a `dict[str, str]` instead of `list[str]`.
Fix: Update existing calls to `docker.secret.create()` to handle the new `Secret` object return type and adjust the `labels` argument to pass a dictionary.
gotcha The `python-on-whales` library executes Docker CLI commands as subprocesses. Therefore, the Docker CLI tools (including `docker`, `docker-compose`, `docker buildx`) must be installed and accessible in the system's PATH for the library to function correctly. This is a separate requirement from installing the Python library itself.
Fix: Ensure Docker Desktop or the standalone Docker CLI tools are installed, running, and configured correctly on your system, and that their binaries are in your system's PATH.
gotcha When running Docker commands that produce continuous output (e.g., `docker.run(...)`, `docker.pull(...)`, `docker.build(...)`), the output might be buffered by default. To process output in real-time or line-by-line, you often need to explicitly pass `stream=True` and then iterate over the result.
Fix: Consult the documentation for specific commands on how to enable and handle streamed output. For example, `for line in docker.run('my-image', stream=True): print(line)`.

Install

pip install python-on-whales Install the library

Imports

docker
```
from python_on_whales import docker
```

Quickstart

This quickstart demonstrates how to import the `docker` client and run a basic `hello-world` container. It verifies Docker is accessible and prints the container's output.

from python_on_whales import docker

# Ensure Docker client is running and accessible
try:
    print(f"Docker info: {docker.info().ServerVersion}")
    print("Running a simple 'hello-world' container...")
    # The output from 'hello-world' will be printed directly to stdout
    docker.run("hello-world")
    print("Hello-world container finished.")
except Exception as e:
    print(f"Error interacting with Docker: {e}")
    print("Please ensure Docker Desktop or the Docker CLI is installed and running.")

view raw JSON →