Developer tools · Docker run to Docker compose converter
The version key in Compose files is obsolete: what replaced it
· Background
docker compose configuration
For years every Compose file began with version: '3'. This post explains what the number used to select, why the Compose Specification dropped it, and what to do with the files you have.
A new warning on every command — 'version is obsolete' on a file that has worked unchanged for years
A new warning on every command — 'version is obsolete' on a file that has worked unchanged for years. Evidence: the writer starts at services and tests reject a top-level version key. Reproduce version key removal with disposable literals. Pair each source occurrence with versionless services output; reserve legacy compatibility for destination review.
The configuration incident also reveals that A separate configuration incident boundary is that the supported result is one version-less limited document. Evidence: the supported result is one version-less limited document. This version key removal constraint is a stopping point. Inspect versionless services output without manufacturing behavior, then document a host check for legacy compatibility.
This repository verifies omission of version, not historical engine-to-format compatibility tables
What version: selected — file format 1, 2.x or 3.x, each tied to a minimum Docker Engine and a set of allowed keys. Evidence: no engine-to-format compatibility table exists in this repository; This repository verifies omission of version, not historical engine-to-format compatibility tables. Trace version key removal tokens into versionless services output. Separate ordered values from last-value fields; legacy compatibility is outside collection.
A related configuration mechanism boundary is that for this configuration section keep the original for this configuration section command and warnings for this configuration section beside this candidate file. Evidence: the repository gives no broader runtime or historical proof. Use this version key removal fact to predict one member or scalar in versionless services output. Check warnings before deciding anything about legacy compatibility.
The code does not establish why earlier format branches diverged, so it documents current generated keys
Why 2 and 3 diverged — Swarm-oriented keys in 3, resource limits in 2, and the confusion that caused. Evidence: historical divergence is not explained by converter implementation; The code does not establish why earlier format branches diverged, so it documents current generated keys. Judge version key removal serialization from its model. Quoting in versionless services output protects types but gives no operational proof for legacy compatibility.
The second configuration serialization observation is keep for this configuration section the original command for this configuration section and warnings beside for this configuration section this candidate file that configuration serialization result separates represented for this configuration section configuration from absent context for this configuration section image metadata is outside the configuration serialization transformation. This version key removal output separates settings from unavailable context. Keep versionless services output reviewable and check legacy compatibility independently.
The specification's answer — one schema, no version field, features gated by the Compose implementation instead
The specification's answer — one schema, no version field, features gated by the Compose implementation instead. Stop at the version key removal exception instead of guessing. Any addition near versionless services output needs a deployment-specific reason tied to legacy compatibility.
Another configuration exception constraint is that A separate configuration exception boundary is that legacy Python and Swarm semantics need versioned references. Evidence: legacy Python and Swarm semantics need versioned references. Keep the original version key removal command beside warnings. The comparison shows what versionless services output contains and which legacy compatibility decision remains manual.
What to do with old files — removing the key, checking for v2-only or v3-only keys, and running docker compose config
What to do with old files — removing the key, checking for v2-only or v3-only keys, and running docker compose config. Evidence: removing version cannot validate every remaining legacy key. Build the version key removal example from synthetic names. Make every versionless services output item traceable without exposing production legacy compatibility details.
The same configuration example sample demonstrates that A separate configuration example boundary is that fresh output fits under services without claiming universal compatibility. Evidence: fresh output fits under services without claiming universal compatibility. The paired version key removal fact should be visible in versionless services output. Record that line and avoid assumptions about legacy compatibility.
Worked example: remove only the version line after reviewing all remaining keys
Worked example: modernising a version: '2.1' file — three edits and the before-and-after diff. Evidence: a modernization example should delete only that marker after review; Worked example: remove only the version line after reviewing all remaining keys. Translate the version key removal consequence into one observable versionless services output difference. Docker owns the later legacy compatibility verdict.
The configuration consequence implementation also shows for this configuration section keep the original for this configuration section command and warnings beside for this configuration section this candidate file that configuration consequence fact defines what for this configuration section the browser contributed for this configuration section docker still owns the configuration consequence runtime verdict the for this configuration section operator still owns the configuration consequence security policy the for this configuration section repository still needs the configuration consequence secret removed keep for this configuration section those responsibilities separate when for this configuration section describing the generated service. Split version key removal responsibilities: conversion writes versionless services output, the repository removes secrets, and operators validate legacy compatibility.
Legacy Python-tool requirements and Swarm deploy behavior are not inferred from this converter
What this does not cover — the old Python docker-compose v1, which still requires the key, and Swarm-specific deploy settings. Evidence: legacy Python and Swarm semantics need versioned references; Legacy Python-tool requirements and Swarm deploy behavior are not inferred from this converter. Limit version key removal scope to versionless services output branches shown here. Neighboring forms and defaults cannot answer legacy compatibility questions.
One more configuration scope limit follows from keep the original command for this configuration section and warnings beside this candidate file. Treat this version key removal boundary as an exclusion. Prefer accurate versionless services output over guesses about legacy compatibility.
Takeaway: the file format has one current shape — and a freshly converted service definition fits under services: without a version line
Takeaway: the file format has one current shape — and a freshly converted service definition fits under services: without a version line. Audit version key removal as source option, model field, versionless services output line and warning. Remove secrets before checking legacy compatibility.
Finally, the configuration takeaway source confirms A separate configuration decision boundary is that historical divergence is not explained by converter implementation. Evidence: historical divergence is not explained by converter implementation. Close version key removal narrowly: versionless services output is a candidate; legacy compatibility and shell equivalence are not guarantees.