Docker Compose v5.7.0: Go API Breaks, and down -v Keeps Foreign Volumes

Go programs that import Compose as a library and call api.Compose.Up, set DownOptions.Images, or reference the hash helpers need changes before they upgrade to Docker Compose v5.7.0. The release notes open with a heads-up for library users, and the CLI additions in the same release are listed below for completeness.

• Up runs its Create and Start phases as one plan over one daemon snapshot, for up -d and interactive up.
• Up returns an *api.IncompatibleOptionsError for two option combinations that the notes say were silently ignored.
• DownOptions.Images is now an api.ImagePruneMode, and invalid values are rejected before Down removes anything.
• compose.ServiceHash, compose.NetworkHash and compose.VolumeHash are no longer exported.
• The interactive keyboard menu is no longer built by the library and needs an explicit opt-in.
• push gains --ignore-missing, and PushOptions.IgnoreMissing is added to the library.
• A service can opt out of its name as a network alias with use_service_name_alias: false.
• For CLI users, down -v no longer removes named volumes the project does not own, and use_api_socket credentials are handed over with tighter permissions.

Up Runs Create and Start as One Plan #

The release notes say Up now runs its Create and Start phases as a single plan over a single daemon snapshot, for up -d (#14290) and interactive up (#14305). The notes add that scale, watch rebuilds and start already work this way, and that the CLI behaves as before.

Up now runs its Create and Start phases as a single plan over a single daemon snapshot

Docker Compose v5.7.0 release notes

For library callers, the daemon is not observed again between the two phases. A container that exits after the plan is built is not started again, and a container removed in between makes its start fail instead of being skipped. A planning error in the Start phase now fails before any container is created, so error handling should expect a start failure in that window.

Up works on the project it is given and ignores StartOptions.Project, so code that sets that field and expects a different project must change. The notes also say a foreground Up now gives a use_api_socket service its /run/secrets/docker/config.json, as up -d does, and shows the output of pre_start hooks.

Up Rejects Two Option Combinations Before Running #

UpOptions.Validate() returns an *api.IncompatibleOptionsError, which matches errors.Is(err, api.ErrIncompatibleOptions). The error is raised for Start.Wait combined with Start.Attach, and for a detached Up (no Start.Attach) combined with OnExit, ExitCodeFrom or Watch. The validation uses the same rules as the CLI flags.

The notes say these combinations were silently ignored (#14306), so code that sets them will now receive an error instead of running. Check each Up call that sets Start.Wait, OnExit, ExitCodeFrom or Watch, and handle the typed error where those combinations can occur.

DownOptions.Images Is Now a Typed Prune Mode #

DownOptions.Images is now an api.ImagePruneMode (#14149). Untyped constants still compile, but a string variable needs a conversion. Invalid values are rejected before Down removes anything, so a bad setting fails the call instead of deleting images first.

Hash Helpers Leave the Public compose Package #

compose.ServiceHash, compose.NetworkHash and compose.VolumeHash are no longer exported (#14405), because the helpers moved to an internal package, internal/confighash. Go does not allow importing an internal package from outside the module, so external code has no direct replacement and needs its own hashing.

The same release also splits api.Compose into six smaller interfaces with the same method set (#14322). Code that calls methods on api.Compose should need no edits for that item.

Interactive up Needs an Explicit Navigation Menu #

The keyboard menu of an interactive up is no longer built by the library (#14324). Set NavigationMenu: true and pass an implementation with compose.WithNavigationMenu(...). Otherwise no menu is displayed, and a warning says so.

push Gains --ignore-missing and Deprecates --ignore-push-failures #

push --ignore-missing skips images that are not available locally (#14341), and PushOptions.IgnoreMissing is the library equivalent. In the same release, --ignore-push-failures is deprecated in favour of --ignore-missing (#14354). The notes do not say that the new flag covers push failures in general, so check that skipping unavailable images fits your CI before replacing the old flag.

Network Alias Opt-Out for a Service #

The release lets a service opt out of its name as a network alias (#14342). PR #14342 explains the setting: with use_service_name_alias: false on a service's networks entry, the service name is not registered as a DNS alias on that network, while the container name alias, the user's aliases and the service's other networks stay. It lets two projects that share a network run a service with the same name without the name resolving to either container.

CLI Changes: down -v and use_api_socket Credentials #

Two fixes change what the command line does. down -v no longer removes a named volume the project does not own, one labeled for another project or one created outside Compose; it skips such a volume with a warning, and if a volume cannot be inspected, down now fails instead of removing it, according to PR #14374. Scripts that relied on down -v to clear shared volumes need an explicit docker volume rm. The release also hardens the credentials handed to a use_api_socket service (#14402) and gives a started use_api_socket service its config file (#14393).

Other CLI fixes: bridge commands reject --dry-run (#14307), watch skips sync and exec triggers on bind-mounted paths (#14328) and ignores .git at any depth (#14363), and an attached up honors -t when it stops the application (#14395). v5.7.1 followed on November 11 with fixes that verify fetched OCI manifests against their digest, keep extracted-project caches consistent and preserve images outside the selected services on down.

Go Library Callers and CI Pipelines That Must Act #

Teams that call api.Compose from their own Go programs are affected by the planning change, the validation change and the removed or retyped names. Teams whose CI runs push with --ignore-push-failures are affected by the deprecation. Teams that only run the CLI are not affected by the library items, but the down -v and use_api_socket changes above do reach them.

Upgrade Checklist #

Complete these steps before moving to v5.7.0:

1. Search for DownOptions.Images and convert any string variable to api.ImagePruneMode.
2. Search for compose.ServiceHash, compose.NetworkHash and compose.VolumeHash; external code must implement its own hashing.
3. Check scripts that use down -v to remove volumes shared with other projects or created outside Compose.
4. Check Up calls that set Start.Wait, OnExit, ExitCodeFrom or Watch, and handle errors.Is(err, api.ErrIncompatibleOptions).
5. For interactive up in library code, set NavigationMenu: true and pass compose.WithNavigationMenu(...).
6. In CI scripts that call push --ignore-push-failures, switch to --ignore-missing, which skips images not available locally.

Also in this release #

Minor items, one line each:

• umask service attribute supported (#14367).
• run --no-recreate reuses existing dependencies as they are (#14144).
• stats --all-projects and --aggregate flags added (#14337).
• Bake's --parallel limit is passed as --jobs (#14352).
• Docker Hub registry credentials come from the Docker Desktop Hub session (#14295).
• pre_start hooks receive the service env_file and environment (#14293).
• Security dependency updates include golang.org/x/net v0.60.0, containerd v2.4.2, and Go 1.26.9 and 1.26.10.

The notes list many further fixes and dependency updates, including watch, logs, bake and executor changes. The full list is in the Docker Compose v5.7.0 release notes.