Docker Compose (Legacy Python Library)

1.29.2 · abandoned · verified Sat Apr 11

The `docker-compose` PyPI package (version 1.x) is the legacy Python library and CLI for defining and running multi-container Docker applications. This specific package is no longer actively maintained, having been superseded by the Go-based Docker Compose CLI (available as `docker compose`). It offers a programmatic interface for interacting with Compose projects, though its API was never officially stable.

Warnings

breaking The 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.
Fix: For 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.
gotcha There 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*.
Fix: Be 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.
gotcha The 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.
Fix: For 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.
gotcha The '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.
Fix: Always 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.

Install

pip install docker-compose Install legacy Python library

Imports

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).

Quickstart

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.")

view raw JSON →