Docker Compose 5.4 Adopts Declarative Reconciliation — Your Volumes and Networks Become a Plan, Not a Script

August 3, 2026. Docker Inc. shipped Compose v5.4.0. Two lines in the changelog. A quiet revolution for the 95% of developers who use Compose daily.

The two features — model volume recreation in the plan and model network lifecycle in the plan — don’t look like much on paper. But they introduce a concept that Kubernetes spent a decade refining and Terraform imposed on cloud infrastructure: declarative reconciliation.

Your compose.yml file is no longer a sequence of instructions. It’s a desired state that the engine compares against reality, then corrects.

What reconciliation changes for volumes

Before Compose 5.4, volume lifecycle was binary: it exists, or it doesn’t. docker compose up created missing volumes. docker compose down removed them (with -v). Nothing happened in between.

With reconciliation, Compose now models the volume as a first-class resource in an execution plan. In practice:

• A volume whose configuration changed — driver opts, labels, name — is detected as diverging from the desired state.
• Compose can now recreate a volume cleanly: drain data, remove, recreate with the new configuration.
• The plan is visible before execution. No more surprises when docker compose up -d decides to recreate a container or volume.

For teams managing multi-service stacks with named volumes, this evolution significantly reduces silent configuration errors. A misconfigured volume no longer persists indefinitely in production — Compose flags it and offers to fix it.

# compose.yml — Compose 5.4 detects configuration drift
services:
  postgres:
    image: postgres:17
    volumes:
      - pgdata:/var/lib/postgresql/data

volumes:
  pgdata:
    driver: local
    driver_opts:
      type: none
      device: /mnt/fast-ssd/pgdata
      o: bind

If you change device from /mnt/fast-ssd to /mnt/nvme-raid, Compose 5.4 models the volume recreation in the plan. You see what’s about to happen before any data is affected.

Networks enter the plan as well

The same treatment applies to networks. Compose 5.4 models the complete lifecycle of a network in the reconciliation plan:

• Creation, driver option updates, subnet changes.
• IP range conflict detection between networks in the same stack.
• Clean removal when a network is no longer referenced by any service — no orphaned networks left behind.

For multi-service deployments with segmented networks (frontend, backend, monitoring), this modeling eliminates the classic network not found error after a docker compose down && docker compose up cycle.

A pattern borrowed from Kubernetes — and that’s a good thing

Reconciliation is the heart of the Kubernetes control loop. The controller observes the cluster’s actual state, compares it to the desired state (the YAML manifests), and takes corrective action. This pattern has proven itself at the scale of millions of containers.

Docker Compose doesn’t target the same scale. But it targets the same reliability. A developer running docker compose up expects their environment to match the compose.yml file. Not “roughly match.” Not “match except for the network we forgot to remove last time.” Match.

The reconciliation engine in Compose 5.4 applies this philosophy at the workstation and small server scale. It’s a paradigm shift bigger than the lines of code that implement it.

Other improvements in v5.4.0

The 5.4 release goes beyond reconciliation. Several fixes improve day-to-day reliability:

• Zero-replica service hashing preserved during reconciliation — your disabled services aren’t accidentally removed.
• Explicit warnings when --service selection is silently ignored by a command.
• Multi-platform build fix: Compose now uses the manifest image digest, not the attested index, for multi-arch builds.
• --insecure-registry honored during OCI model reload — self-signed private registries work correctly.
• Tolerant environment variables: runtime commands like scale, watch, and shell completion no longer fail when a .env file is missing.

One notable detail for DevOps teams: Docker Compose now adopts the AGENTS.md standard and requires a dated AI_AGENT_DISCLOSURE.md file for any AI-assisted contribution. A first in the Docker ecosystem — and a signal that open source contribution supply chains are becoming a governance concern.

What this means for your CI pipelines

Declarative reconciliation directly impacts CI pipelines. Many teams use Compose in their integration jobs to spin up services needed for testing:

# .github/workflows/test.yml
- name: Start services
  run: docker compose up -d --wait postgres redis
- name: Run tests
  run: go test ./...

With Compose 5.4, docker compose up guarantees that volumes and networks are exactly in the state specified by compose.yml. No drift between runs. No orphaned network that persists and corrupts the next test. Test environment reproducibility takes a tangible step forward.

The verdict

Docker Compose 5.4 is not a major version bump. But it lays the first brick of a reconciliation engine that moves Compose closer to the reliability standards of declarative infrastructure.

If you run Compose in production — on a VPS, a bare metal server, or in a CI pipeline — this update makes your stack more reliable without changing a single line of your YAML files. That’s the best kind of update: the one that improves operational safety without demanding a migration.

Check your version with docker compose version, then follow the official installation instructions. v5.4.0 is available on GitHub Releases and through package managers.

References

• Docker Compose v5.4.0 Release Notes
• Docker Compose documentation — Volumes
• Kubernetes — Controllers and Reconciliation