How to fix version is obsolete in Docker

DockerBEGINNERLOW

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 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.

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 |

How to fix version is obsolete in Docker

What this error means

Typical symptoms

Common causes

How to fix "version is obsolete"

Advanced notes

Related errors

Official resources & further reading