Docker Compose v5.7.0: Library API Changes for Go Callers

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.

Up Runs Create and Start as One Plan #

One plan, one daemon snapshot: 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 #

Typed error for incompatible options: 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 #

String fields need a conversion: 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 #

Three names are no longer exported: compose.ServiceHash, compose.NetworkHash and compose.VolumeHash are no longer exported (#14405), because the helpers moved to an internal package. Any reference to these names stops compiling against v5.7.0. The notes do not name a replacement, so find every call to these helpers before upgrading.

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 #

Menu must be enabled and supplied: 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 #

New flag skips images not available locally: 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 #

A service can drop its name as an alias: the release lets a service opt out of its name as a network alias (#14342). The notes do not describe its effect on name resolution, so test a service with the opt-out before relying on it.

Go Library Callers and CI Pipelines That Must Act #

Library callers and push-based CI are affected: 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, since the notes state that the CLI behaves as before.

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, and remove or replace those uses.
3. Check Up calls that set Start.Wait, OnExit, ExitCodeFrom or Watch, and handle errors.Is(err, api.ErrIncompatibleOptions).
4. For interactive up in library code, set NavigationMenu: true and pass compose.WithNavigationMenu(...).
5. In CI scripts that call push --ignore-push-failures, confirm that --ignore-missing fits the job, then switch.

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.