Install & Compatibility
Where this runs
tested against v1.29.2 · 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
py 3.10
✕ build_error
✕ build_error
py 3.11
✕ build_error
✕ build_error
py 3.12
✕ build_error
✕ build_error
py 3.13
✕ build_error
✕ build_error
py 3.9
✕ build_error
✓ 6.6s
55MB installed
● package 55MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Project
✓ from compose.project import Project
Primary class for managing Compose projects.
get_project
✓ from compose.cli.command import get_project
Function often used to load a project, similar to how the CLI does.
main
✓ from compose.cli.main import main
For directly invoking the CLI's main function programmatically (less common for library use).
Demonstrates how to programmatically define, start, and stop a Docker Compose project using the legacy Python library. This example dynamically creates a `docker-compose.yml` file and uses `get_project` to manage it. Requires Docker daemon to be running.
import os
import tempfile
from pathlib import Path
from compose.cli.command import get_project # This is often used to load a project
# Create a dummy docker-compose.yml for demonstration
compose_content = """
version: '3.8'
services:
web:
image: nginxdemos/hello:latest
ports:
- "8080:80"
"""
# Use a temporary directory for the project context
with tempfile.TemporaryDirectory() as tmpdir:
project_path = Path(tmpdir)
compose_file = project_path / "docker-compose.yml"
compose_file.write_text(compose_content)
print(f"Created temporary docker-compose.yml at: {compose_file}")
try:
# Set a project name; otherwise, it might infer from directory name
os.environ['COMPOSE_PROJECT_NAME'] = project_path.name
# get_project mimics the CLI's way of loading a project
project = get_project(project_path, [str(compose_file)])
print(f"Starting project '{project.name}'...")
project.up() # Starts services
print("Project started. Check http://localhost:8080 (if Docker is running and port is free)")
print("Listing services...")
for service in project.services:
print(f"- Service: {service.name}")
print("Stopping and removing project...")
project.down(remove_volumes=True) # Stops and removes containers, networks, volumes
print("Project removed.")
except Exception as e:
print(f"An error occurred: {e}")
print("Ensure Docker is running and the 'docker-compose' Python library is installed.")
docker-compose --version
Debug
Known issues
breakingThe Python 'docker-compose' library (v1.x) is officially abandoned and no longer maintained. All new Docker Compose features and development are exclusively for the Go-based 'docker compose' CLI. This package will not receive updates or bug fixes.fixFor programmatic interaction with Docker, migrate to using the 'docker' Python SDK (`docker-py`). For orchestrating multi-container applications, use the standalone 'docker compose' CLI binary directly via subprocess calls or migrate to a more modern orchestration tool.
affects: All versions of the 'docker-compose' PyPI package (1.x).
gotchaThere are two distinct 'docker compose' implementations: the legacy Python library (installed via `pip install docker-compose`, invoked as `docker-compose`) and the modern Go-based CLI (part of Docker Desktop or standalone binary, invoked as `docker compose`). This registry entry is for the *legacy Python library*.fixBe explicit about which implementation you are using. For new projects, use the Go-based `docker compose` CLI. Avoid installing the `docker-compose` PyPI package unless you specifically need the legacy Python API for existing projects.
affects: All versions.
gotchaThe Python API of the 'docker-compose' library was never officially stable or intended for broad public use, primarily serving the internal CLI. Expect brittle, undocumented, and potentially breaking behavior in minor updates.fixFor stable and well-documented programmatic control of Docker, consider using the `docker-py` library directly. If you must use `docker-compose` v1.x's API, pin your version and thoroughly test interactions.
affects: All versions of 1.x.
gotchaThe 'version' field in `docker-compose.yml` refers to the *Compose file format specification*, not the version of the `docker-compose` tool itself. Using an old file format version (e.g., '2.x') might limit available features.fixAlways specify a modern `version` (e.g., `'3.8'`) at the top of your `docker-compose.yml` file to ensure compatibility and access to the latest Compose file features.
affects: All versions.
Upgrade
Version history
1.29.2latest on PyPI · released May 10, 2021
Audit
Dependencies
dockerrequiredRequired for interacting with the Docker daemon.