{"id":1682,"library":"python-on-whales","title":"python-on-whales","description":"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.","status":"active","version":"0.81.0","language":"en","source_language":"en","source_url":"https://github.com/gabrieldemarmiesse/python-on-whales","tags":["docker","container","cli","orchestration","devops","automation"],"install":[{"cmd":"pip install python-on-whales","lang":"bash","label":"Install the library"}],"dependencies":[],"imports":[{"symbol":"docker","correct":"from python_on_whales import docker"}],"quickstart":{"code":"from python_on_whales import docker\n\n# Ensure Docker client is running and accessible\ntry:\n    print(f\"Docker info: {docker.info().ServerVersion}\")\n    print(\"Running a simple 'hello-world' container...\")\n    # The output from 'hello-world' will be printed directly to stdout\n    docker.run(\"hello-world\")\n    print(\"Hello-world container finished.\")\nexcept Exception as e:\n    print(f\"Error interacting with Docker: {e}\")\n    print(\"Please ensure Docker Desktop or the Docker CLI is installed and running.\")","lang":"python","description":"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."},"warnings":[{"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`.","message":"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.","severity":"breaking","affected_versions":"0.74.0 and later"},{"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.","message":"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]`.","severity":"breaking","affected_versions":"0.76.1 and later"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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)`.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}