Docker Compose v5: the Go SDK that changes everything for automation

On February 14, 2026, Docker announced the general availability of Docker Compose v5, marking a major break from previous versions. Unlike v2-v4, which were written in Python, v5 is fully rewritten in Go and, for the first time, exposes a native SDK for programmatic automation. This shift turns Compose from a simple CLI into a lightweight, programmable orchestration framework, bridging the gap between local development and production deployment.

Why rewrite Compose in Go?

Docker Compose v2-v4 were written in Python with bindings to external services. That architecture had several limitations. With the rise of Kubernetes and the growth of decentralized orchestration use cases (Nomad, Swarm, edge compute), Docker decided to modernize Compose to stay relevant.

The Go rewrite delivers:

• Performance: instant startup, YAML parsing in a few milliseconds.
• Distribution: a statically linked binary, zero external dependencies.
• Cross-platform: native compilation for Linux ARM64, Windows, and macOS without friction.
• Exposed SDK: the orchestration logic becomes a reusable library.
• Maintainability: a modern, modular codebase.

Compose v5's modular architecture

Compose v5 is structured into reusable packages:

github.com/docker/compose/v5
├── /api           # Publicly exposed SDK
├── /cli           # Command-line interface
├── /loader        # YAML parser and validation
├── /engine        # Container lifecycle management
└── /integration   # Hookup with the Docker Daemon

A public SDK for automation

The big news: an official, stable Go SDK.

import "github.com/docker/compose/v5/api"

// Create a composition and launch it programmatically
composer := api.NewComposer(
  api.WithFile("docker-compose.yml"),
  api.WithProject("my-app"),
)

// Up
if err := composer.Up(context.Background()); err != nil {
  log.Fatal(err)
}

// Query services status
services, err := composer.Services(context.Background())
for _, svc := range services {
  fmt.Printf("%s: %s\n", svc.Name, svc.State)
}

// Down
composer.Down(context.Background())

This SDK exposes:

• Composer.Up/Down: lifecycle management.
• Composer.Services: query the state of services.
• Composer.Logs: real-time log streaming.
• Composer.Exec: run commands inside containers.
• Composer.Events: webhooks and lifecycle events.
• Composer.Config: programmatic access to the configuration.

Real-time streaming and events

Unlike v2-v4, v5 implements an asynchronous event system:

// Listen to a service's events
events := composer.WatchService(ctx, "api", api.ServiceEventFilter{
  Types: []string{"start", "stop", "error"},
})

for event := range events {
  switch event.Type {
  case "start":
    log.Printf("Service %s started with PID %d\n", event.ServiceName, event.PID)
  case "error":
    log.Printf("Service %s failed: %s\n", event.ServiceName, event.Error)
  }
}

This enables sophisticated monitoring and automation tools without constant polling.

Advanced profile support

Compose v2 profiles let you select groups of services, but v5 improves on them:

services:
  api:
    image: api:latest
    profiles: [prod]
  redis:
    image: redis:latest
    profiles: [cache]
  monitoring:
    image: prometheus:latest
    profiles: [debug, prod]

Through the SDK:

composer := api.NewComposer(
  api.WithFile("docker-compose.yml"),
  api.WithProfiles([]string{"monitoring", "cache"}),
)
composer.Up(ctx)

Migrating from Compose v2/v4

Full backward compatibility

Docker Compose v5 is 100% backward compatible with v2 and v4 docker-compose.yml files. Existing files run without modification.

curl -L "https://github.com/docker/compose/releases/download/v5.0.0/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
chmod +x /usr/local/bin/docker-compose
docker-compose version

SDK use cases

1. Programmatic orchestration in Go

Embed Compose directly inside a Go application:

package main

import (
  "context"
  "github.com/docker/compose/v5/api"
)

func main() {
  composer := api.NewComposer(api.WithFile("docker-compose.yml"))

  // Start all services
  composer.Up(context.Background())

  // Wait until the API is ready
  composer.WaitForService(context.Background(), "api", 30*time.Second)

  // Run tests
  result, err := composer.Exec(context.Background(), "api", []string{"npm", "test"})

  // Clean up
  composer.Down(context.Background())
}

2. Terraform / Infrastructure as Code

Write a Terraform provider for Compose:

resource "docker_compose_stack" "app" {
  compose_file = file("${path.module}/docker-compose.yml")
  project_name = "myapp"

  environment = {
    DATABASE_URL = "postgres://..."
  }
}

output "services" {
  value = docker_compose_stack.app.services
}

3. CI/CD with the Docker Compose API

GitHub Actions with automatic testing and cleanup:

name: Test with Compose v5 API

on: [push]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - uses: actions/setup-go@v4
        with:
          go-version: 1.22

      - name: Run tests with Compose SDK
        run: |
          go run ./cmd/test-runner.go \
            --compose-file docker-compose.test.yml \
            --services api,postgres

Performance vs v2/v4

Kubernetes integration

Compose to Kubernetes is now native:

docker-compose convert --format kubernetes > deployment.yaml

The generated file is ready to apply to Kubernetes:

kubectl apply -f deployment.yaml

Security: native secrets

Compose v5 builds in secrets management:

services:
  api:
    image: api:latest
    secrets:
      - db_password
      - api_key

secrets:
  db_password:
    external: true  # Provided via docker secret
  api_key:
    file: ./secrets/api_key.txt

Through the SDK:

composer := api.NewComposer(
  api.WithFile("docker-compose.yml"),
  api.WithSecrets(map[string]string{
    "db_password": os.Getenv("DB_PASSWORD"),
    "api_key": os.Getenv("API_KEY"),
  }),
)
composer.Up(ctx)

Limitations and considerations

• SDK v1: the API may evolve toward v2 by 2027.
• Swarm: declining support (Docker is steering toward Kubernetes).
• Windows: some volumes remain limited on WSL2.

Conclusion

Docker Compose v5 marks the maturation of lightweight orchestration. With a native Go SDK, dramatically improved performance, and a modular architecture, Compose v5 becomes a viable choice for production orchestration, not just local development.

For DevOps engineers and backend developers, this release is a must-have upgrade. The performance gain alone (46x faster on parsing) justifies migrating right away.