Docker Compose "the attribute version is obsolete" Warning

By Kaveh Alemi·Latchkey

The top-level version: key in compose files is obsolete in Compose v2 and is ignored. The warning itself is harmless - but it often appears right next to a real v1-vs-v2 problem.

What this error means

Every docker compose command prints the attribute "version" is obsolete, it will be ignored. The command still runs; the noise can mask a more important error in the same output.

docker compose output

WARN[0000] /app/docker-compose.yml: the attribute `version` is obsolete,
it will be ignored, please remove it to avoid potential confusion

Diagnose it: read the resolved config, not the file you wrote

Compose merges override files, interpolates variables, and applies defaults before it does anything. Most Compose failures in CI are visible in the resolved configuration and invisible in the source file, because the value you are debugging came from an unset variable that quietly became an empty string.

Terminal

# the fully merged, interpolated configuration Compose will actually run
docker compose config

# fail loudly on unset variables instead of silently interpolating empty
docker compose --env-file .env config --quiet || echo "invalid"

# which override files were picked up
docker compose config --services

Common causes

Legacy `version:` key in the compose file

Compose v2 derives the schema from the features used, so the old version: "3.8" declaration is ignored and warned about.

Mixing Compose v1 commands/behavior

Pipelines that still call docker-compose (v1, hyphenated) alongside docker compose (v2) can behave inconsistently; the warning is a hint you are on the v1→v2 boundary.

How to fix it

Remove the version key

Delete the top-level version: line to silence the warning.

docker-compose.yml

# delete this line from docker-compose.yml
version: "3.8"

Standardize on Compose v2

Use docker compose (space) everywhere, not the legacy docker-compose binary.
Confirm the version with docker compose version.
Treat the obsolete-version line as a warning, and scan the same output for the actual error.

Bind mounts behave differently on a runner

A relative bind source is resolved against the compose file location, not the working directory of the shell that invoked it.
The host path must exist before up. Compose creates missing directories for named volumes but not for bind mounts, and the failure surfaces as a mount error rather than a missing-path error.
On a CI runner the workspace path differs from your machine, so any absolute host path in a compose file is a portability bug waiting for its first CI run.
Prefer named volumes for anything that does not genuinely need to be read from the host. They remove the whole class of problem.

How to prevent it

Drop the version: key from compose files.
Use the v2 docker compose plugin consistently in CI.
Do not let the warning distract from real errors in the log.

Frequently asked questions

What causes Docker Compose "the attribute version is obsolete" warning?

There are 2 common causes: legacy version: key in the compose file and mixing compose v1 commands/behavior. Compose v2 derives the schema from the features used, so the old version: "3.8" declaration is ignored and warned about.

How do I fix Docker Compose "the attribute version is obsolete" warning?

There are 2 fixes depending on which cause you have: remove the version key and standardize on compose v2. Work through them in order, since the first is the most common.

What does Docker Compose "the attribute version is obsolete" warning actually mean?

Every docker compose command prints the attribute "version" is obsolete, it will be ignored.

How do I stop Docker Compose "the attribute version is obsolete" warning happening again?

Drop the version: key from compose files. The prevention section lists 3 changes that keep it from recurring.