Install & Compatibility
Where this runs
tested against v0.81.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.806s · 29.1MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 3.4s · import 0.726s · 29MB
27MB installed
● package 27MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
docker
✓ from python_on_whales import docker
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.")
Debug
Known issues
breakingThe `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.fixInstall 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`.
affects: 0.74.0 and later
breakingThe 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]`.fixUpdate existing calls to `docker.secret.create()` to handle the new `Secret` object return type and adjust the `labels` argument to pass a dictionary.
affects: 0.76.1 and later
gotchaThe `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.fixEnsure 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.
affects: All versions
gotchaWhen 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.fixConsult 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)`. affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'python_on_whales'
The `python-on-whales` library is not installed in the Python environment where the code is being executed.
fixInstall the library using pip: `pip install python-on-whales`
docker.exceptions.DockerException: An unexpected error occurred. Docker daemon is not running?
The Docker daemon service is not running on the host machine, preventing `python-on-whales` from connecting to and executing Docker commands.
fixStart the Docker daemon on your system (e.g., open Docker Desktop application on Windows/macOS, or use `systemctl start docker` on Linux).
AttributeError: 'Container' object has no attribute 'log'
The user is attempting to access container logs as an attribute (`.log`) instead of calling the appropriate method (`.logs()`).
fixUse the `logs()` method to retrieve container logs: `container.logs()`
docker.exceptions.ContainerRuntimeException: The command 'your_command' in container 'your_container' returned a non-zero exit code.
A command executed inside a Docker container using `docker.run()` or similar methods failed, exiting with a non-zero status code.
fixInspect the container logs (e.g., `container.logs()`) or manually run the command with `docker run` to debug why the command failed inside the container.
docker.exceptions.DockerException: ERROR: Can't find a suitable configuration file in this directory or any parent. Are you in the right directory?
When using `docker.compose` commands, the `docker-compose.yml` file is not found in the current working directory or at the specified path.
fixEnsure the `docker-compose.yml` file is present in the directory where your script is run, or specify its path explicitly using the `files` argument, e.g., `docker.compose.up(files=['/path/to/docker-compose.yml'])`.
Upgrade
Version history
0.81.0latest on PyPI · released Mar 9, 2026
Audit
Dependencies
No dependency data recorded yet.