{"id":3978,"library":"docker-compose","title":"Docker Compose (Legacy Python Library)","description":"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.","status":"abandoned","version":"1.29.2","language":"en","source_language":"en","source_url":"https://github.com/docker/compose","tags":["docker","container","orchestration","legacy","abandoned"],"install":[{"cmd":"pip install docker-compose","lang":"bash","label":"Install legacy Python library"}],"dependencies":[{"reason":"Required for interacting with the Docker daemon.","package":"docker","optional":false}],"imports":[{"note":"Primary class for managing Compose projects.","symbol":"Project","correct":"from compose.project import Project"},{"note":"Function often used to load a project, similar to how the CLI does.","symbol":"get_project","correct":"from compose.cli.command import get_project"},{"note":"For directly invoking the CLI's main function programmatically (less common for library use).","symbol":"main","correct":"from compose.cli.main import main"}],"quickstart":{"code":"import os\nimport tempfile\nfrom pathlib import Path\nfrom compose.cli.command import get_project # This is often used to load a project\n\n# Create a dummy docker-compose.yml for demonstration\ncompose_content = \"\"\"\nversion: '3.8'\nservices:\n  web:\n    image: nginxdemos/hello:latest\n    ports:\n      - \"8080:80\"\n\"\"\"\n\n# Use a temporary directory for the project context\nwith tempfile.TemporaryDirectory() as tmpdir:\n    project_path = Path(tmpdir)\n    compose_file = project_path / \"docker-compose.yml\"\n    compose_file.write_text(compose_content)\n\n    print(f\"Created temporary docker-compose.yml at: {compose_file}\")\n\n    try:\n        # Set a project name; otherwise, it might infer from directory name\n        os.environ['COMPOSE_PROJECT_NAME'] = project_path.name\n        # get_project mimics the CLI's way of loading a project\n        project = get_project(project_path, [str(compose_file)])\n\n        print(f\"Starting project '{project.name}'...\")\n        project.up() # Starts services\n        print(\"Project started. Check http://localhost:8080 (if Docker is running and port is free)\")\n\n        print(\"Listing services...\")\n        for service in project.services:\n            print(f\"- Service: {service.name}\")\n\n        print(\"Stopping and removing project...\")\n        project.down(remove_volumes=True) # Stops and removes containers, networks, volumes\n        print(\"Project removed.\")\n\n    except Exception as e:\n        print(f\"An error occurred: {e}\")\n        print(\"Ensure Docker is running and the 'docker-compose' Python library is installed.\")","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":"All versions of the 'docker-compose' PyPI package (1.x)."},{"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.","message":"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*.","severity":"gotcha","affected_versions":"All versions."},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions of 1.x."},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions."}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}