How to fix version is obsolete in Docker

DockerBEGINNERLOWUpdated Dec 6, 2025· 830 views

The 'version is obsolete' warning appears when running Docker Compose V2 with a docker-compose.yml file that includes the deprecated `version:` field. This is a harmless warning that can be resolved by simply removing the version line from your Compose file.

Quick fix

Fixes version is obsolete

docker compose version
  1. Verify you're using Docker Compose V2
  2. Remove the version field from docker-compose.yml
  3. Check for override and additional Compose files
  4. Verify the warning is resolved
docker — error
docker compose version
version is obsolete

What this error means

The "version is obsolete" warning indicates that your docker-compose.yml file contains a `version:` field that is no longer needed by Docker Compose V2. Docker Compose has evolved through several generations: - **Compose V1** (the standalone `docker-compose` Python tool) required the `version:` field to specify which schema features were available (versions 2.x, 3.x, etc.) - **Compose V2** (the modern `docker compose` plugin, written in Go) uses the Compose Specification and no longer needs this field Starting with Docker Compose V2 (version 2.0+, released as GA in 2022), the version field became purely informational. Compose V2 automatically uses the latest schema and validates your file based on the features you actually use, not a declared version number. When you see `WARN[0000] docker-compose.yml: \`version\` is obsolete`, Docker is telling you the version field will be ignored. Your Compose file still works - this is just a deprecation warning, not an error.

Typical symptoms

  • Warning message: `WARN[0000] /path/to/docker-compose.yml: \`version\` is obsolete`
  • Warning appears every time you run `docker compose up`, `docker compose build`, or other compose commands
  • Message states: "the attribute `version` is obsolete, it will be ignored, please remove it to avoid potential confusion"
  • Compose commands complete successfully despite the warning
  • CI/CD logs show the warning before container operations
  • Warning appeared after upgrading Docker or Docker Compose to a newer version

Common causes

  1. The docker-compose.yml file contains a `version:` field (e.g., `version: '3.8'`) which is now deprecated in Compose V2
  2. Docker Compose was upgraded from V1 to V2, which treats the version field as obsolete
  3. Compose file was created from an older tutorial, template, or documentation that still includes the version field
  4. Multiple Compose files (including override files) contain the version field
  5. Project was cloned from a repository that hasn't updated its Compose files for V2

How to fix "version is obsolete"

1Verify you're using Docker Compose V2

First, confirm which version of Docker Compose you're using:

bash
docker compose version

You should see output like:

bash
Docker Compose version v2.24.0

If the version starts with v2., you're using Compose V2 and the version field is indeed obsolete. If you're still on V1 (versions like 1.29.x), you won't see this warning.

2Remove the version field from docker-compose.yml

Open your docker-compose.yml file and remove the version: line at the top:

Before:

yaml
version: '3.8'
services:
  web:
    image: nginx:latest
    ports:
      - "80:80"
  db:
    image: postgres:15

After:

yaml
services:
  web:
    image: nginx:latest
    ports:
      - "80:80"
  db:
    image: postgres:15

The version field is the only thing you need to remove. All other content remains unchanged.

You can also do this with sed:

bash
# Preview the change
sed -n '/^version:/p' docker-compose.yml

# Remove the version line (backup first)
sed -i.bak '/^version:/d' docker-compose.yml
3Check for override and additional Compose files

Docker Compose may also load additional files that contain the version field. Common files to check:

bash
# List common Compose files in your project
ls -la docker-compose*.yml docker-compose*.yaml compose*.yml compose*.yaml 2>/dev/null

Remove the version: field from all of these files:
- docker-compose.yml (main file)
- docker-compose.override.yml (auto-loaded if present)
- docker-compose.dev.yml or docker-compose.prod.yml (environment-specific)
- Any files passed with -f flag

You can check all files at once:

bash
# Find version lines in all compose files
grep -l "^version:" docker-compose*.yml docker-compose*.yaml compose*.yml compose*.yaml 2>/dev/null
4Verify the warning is resolved

After removing the version field, run any Docker Compose command to confirm the warning is gone:

bash
docker compose config

This validates your Compose file and shows the merged configuration. If successful, you should see your service definitions without any warnings.

You can also run:

bash
docker compose up -d

The warning should no longer appear in the output.

5Update CI/CD pipelines and scripts

If you're seeing this warning in CI/CD logs, update your pipeline configuration to ensure all environments use clean Compose files:

GitHub Actions example:

yaml
- name: Start services
  run: docker compose up -d
  # No warnings if version field is removed from compose files

GitLab CI example:

yaml
services:
  script:
    - docker compose up -d

If you can't modify the Compose files (e.g., from a third-party project), you can suppress the warning by redirecting stderr:

bash
docker compose up -d 2>&1 | grep -v "version.*obsolete"

However, removing the version field is the cleaner solution.

Advanced notes

### Why Was the Version Field Deprecated?

The version: field was originally introduced to help Docker Compose understand which features and syntax your Compose file expected. Different versions (2.0, 2.1, 3.0, 3.8, etc.) supported different capabilities.

However, this created several problems:
1. Confusion about which version to use
2. Features arbitrarily split between "version 2" and "version 3" formats
3. Version numbers didn't correspond to docker-compose tool versions

The Compose Specification (adopted by Compose V2) takes a different approach: it validates files based on the actual features used, not a declared version. This makes Compose files more portable and easier to maintain.

### Keeping the Version Field for Documentation

Some teams prefer keeping the version: field as documentation to indicate which Compose file format was intended:

yaml
# Note: version field is obsolete but kept for documentation
version: '3.8'  # Originally written for Compose file format 3.8
services:
  # ...

This is valid - the warning is informational only. Your Compose file will work correctly. However, the warning will continue to appear unless you remove the field.

### Silencing the Warning Without Removing Version

If you cannot modify the Compose file (e.g., in a managed project), you can suppress warnings:

bash
# Using COMPOSE_IGNORE_ORPHANS doesn't help here, but you can filter output
docker compose up -d 2>&1 | grep -v "obsolete"

### Compose V1 vs V2 Command Differences

| Aspect | Compose V1 | Compose V2 |
|--------|-----------|-----------|
| Command | docker-compose | docker compose |
| Version field | Required | Obsolete |
| Installation | Separate tool | Docker plugin |
| Language | Python | Go |
| Performance | Slower | Faster |

### Migration from V1 to V2

If you're migrating from the old docker-compose to docker compose:

1. Remove the version: field from Compose files
2. Replace docker-compose with docker compose in scripts
3. Note that some edge-case behaviors may differ (check Docker migration docs)

### Common Version Numbers and Their History

| Version | Released | Notable Features |
|---------|----------|-----------------|
| 2.0 | 2016 | services/networks/volumes structure |
| 2.1 | 2016 | healthcheck support |
| 3.0 | 2017 | Swarm deploy support |
| 3.4 | 2017 | extension fields |
| 3.8 | 2019 | Last numbered version widely used |
| Spec | 2020+ | Versionless, feature-based |

Frequently asked questions

What does "version is obsolete" mean?
yml file contains a version: field that is no longer needed by Docker Compose V2. 0+, released as GA in 2022), the version field became purely informational. Compose V2 automatically uses the latest schema and validates your file based on the features you actually use, not a declared version number.
How do I fix "version is obsolete"?
The 'version is obsolete' warning appears when running Docker Compose V2 with a docker-compose.yml file that includes the deprecated version: field. This is a harmless warning that can be resolved by simply removing the version line from your Compose file.
What causes "version is obsolete"?
The docker-compose.yml file contains a version: field (e.g., version: '3.8') which is now deprecated in Compose V2 Docker Compose was upgraded from V1 to V2, which treats the version field as obsolete Compose file was created from an older tutorial, template, or documentation that still includes the version field
Is the "version is obsolete" error serious?
It is a low-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading