python-on-whales

What it is and what it does

python-on-whales is a Python wrapper around the Docker CLI that translates Docker commands into intuitive Python method calls. Instead of shelling out to docker run or docker build, you call methods directly from Python code like run(), build(), pull(), and compose operations. It handles container lifecycle management, image operations, volume creation, networking, and Docker Compose orchestration.

The package is designed as a thin, direct mapping of Docker CLI operations to Python, so developers familiar with Docker commands can immediately recognize the equivalent Python calls. It depends on pydantic and typing-extensions for data validation and type hints, and requires Docker or Podman to be installed separately on the host system. The API returns Python objects that can be used as context managers to ensure cleanup, making it suitable for automation scripts, testing frameworks, and CI/CD pipelines.

Use it for:

• Automate container lifecycle in Python test suites by spinning up, configuring, and tearing down containers programmatically.
• Build and push Docker images from Python scripts without subprocess calls or shell escaping.
• Orchestrate multi-container applications using Docker Compose from Python code.
• Copy files between host and containers, manage volumes, and inspect running containers in deployment automation.
• Integrate GPU-enabled containers into Python applications with native parameter passing.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

A Python Docker client that wraps the Docker CLI with an intuitive, Pythonic API for container, image, and compose operations on Linux, macOS, and Windows.

Yes. The package has low install friction, active maintenance, no known vulnerabilities, and a permissive MIT License. It solves a real problem—making Docker operations accessible and type-safe from Python—and is well-positioned for automation, testing, and CI/CD use cases. Install it if you need to orchestrate Docker from Python code.

Install

python-on-whales on PyPI

pip install python-on-whales

uv add python-on-whales

poetry add python-on-whales

Installing python-on-whales

Before you install

Low install friction with only two lightweight runtime dependencies (pydantic and typing-extensions). Active maintenance with recent commits and steady releases since 2020.

License in practice

MIT License permits unrestricted use, modification, and distribution in both open-source and proprietary projects with minimal obligations.

Quickstart

pip install python-on-whales

from python_on_whales import docker

output = docker.run("hello-world")
print(output)

Requires Docker or Podman to be installed and running on the system; Python 3.8 or above.

Verify before relying

• Whether the package supports Podman as a full alternative to Docker or only partial compatibility.
• Performance characteristics when managing large numbers of containers or images.
• Full scope of Docker Compose features supported through the python-on-whales API.

Package facts

Evidence: python_on_whales-0.81.0-py3-none-any.whl

Tags

More Build Tools packages