Docker Compose v3 now maps to the modern Compose Specification; this 2026 reference covers commands, config, profiles, watch, and pitfalls. Read now.
What Compose v3 actually means
Docker Compose v3 is not a separate dialect you maintain forever. In current usage, the old major-version labels on the compose file largely collapse into the Compose Specification: one schema for services, networks, volumes, and the knobs that control how they start together. Treat “v3” as the familiar entry point into that shared model rather than a frozen 3.x feature set you must keep memorizing by minor number.
That mapping changes how you read docs and samples. Prefer the specification’s field names and semantics over folklore from older tutorials. If a guide still frames everything as “compose file version three only,” translate it: check whether the key exists in the modern schema, whether the CLI still accepts it, and whether the behavior matches what your runtime actually does.
The practical payoff is portability of mental model. Once services, build context, env files, and dependency order live under one specification, the same file is easier to reason about across local stacks, CI jobs, and lightweight remote hosts—as long as you stay inside documented fields and avoid tool-specific extensions you cannot reproduce elsewhere.
Commands and config you should keep sharp
Day-to-day work still centers on a short command surface: bring a project up, stream logs, exec into a service, rebuild images when the Dockerfile or build context changes, and tear the project down cleanly. Learn the project-name and file-selection flags early. Multiple compose files are normal—base plus overrides for local secrets, ports, or debug agents—so naming the project and the file set explicitly prevents “wrong stack, right machine” mistakes.
Config is where most breakage hides. Validate the merged file before you rely on it: unresolved variables, conflicting ports, and services that never become healthy all show up as merge or runtime errors rather than syntax errors. Keep environment defaults in the compose file or an env file checked into the repo with safe placeholders; put real credentials outside version control. Prefer explicit service dependencies and health-aware startup over sleep loops in entrypoints when order matters.
- Name the project when more than one stack shares a host.
- Merge base and override files deliberately; print or inspect the result when behavior surprises you.
- Rebuild only what changed; avoid full down/up cycles unless volumes or networks must reset.
- Document required env vars next to the services that consume them.
Profiles and watch for focused local workflows
Profiles let you keep optional services in the same file without starting them every time. Put heavyweight dependencies, mock third parties, load generators, or debug sidecars behind a profile, then enable that profile only when you need them. The default path stays lean for everyday coding; the full path remains one file and one mental model away. Name profiles after jobs or roles, not after individuals, so the same switches work for everyone on the team.
Watch-style workflows close the gap between edit and running container for services you change often. Use them for app code and hot-reloadable assets; do not expect watch alone to replace image rebuilds when the base image, system packages, or native dependencies change. Pair watch with clear boundaries: bind mounts or sync rules for mutable source, rebuild triggers for layers that must bake into the image. That split keeps feedback fast without lying about what is immutable.
Pitfalls that waste hours
The common traps are predictable. Variable substitution fails silently when a name is misspelled or only set in the wrong shell. Volume mounts hide host/OS path differences and permission problems that only appear after the first write. Network aliases and service DNS names are easy to confuse with localhost on the host machine—traffic inside the compose network uses service names, not the host’s published ports. Healthchecks that never pass leave dependents stuck “starting” forever.
Also watch lifecycle drift: old containers from a previous project name, orphaned volumes, or a partial override still applied from a prior command. When something “should work,” inspect the effective config, the running container’s env, and whether you are attached to the network you think you are. A short, consistent project layout—compose files at a known root, env samples committed, profiles documented in the README—prevents most of these issues more reliably than clever one-off flags.