---
id: python-on-whales
version: "0.81.0"
license: MIT License Copyright (c) 2020 Gabriel de Marmiesse de Lussan Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the… (full text in the JSON record)
license_treatment: permissive
maintenance: active
---

# python-on-whales — A Docker client for Python, designed to be fun and intuitive!

License: permissive · Maintenance: active · Downloads: 12.8M/mo

## 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 above — 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

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

- License: MIT License Copyright (c) 2020 Gabriel de Marmiesse de Lussan Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the… (full text in the JSON record) (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 12.8M/month (top 5,000 on PyPI)
- Known vulnerabilities: none known

## Tags

docker client python, python docker api wrapper, docker container management python, docker compose automation, pythonic docker cli, docker build run pull python, container orchestration python, docker-automation, container-orchestration, devops-tooling

[View on SkillFed](https://skillfed.io/packages/python-on-whales) · [View on PyPI](https://pypi.org/project/python-on-whales/)