Docker Compose Validator

What the Docker Compose Validator Checks

The validator parses your docker-compose.yml in the browser and runs a practical set of checks on top of the YAML syntax: every service must define an image or a build section, port mappings must use valid syntax, depends_on entries must reference services that actually exist, restart policies must be one of the four Compose values, and no two services may publish the same host port. It also flags best practice issues such as unpinned images, missing restart policies, privileged containers, fixed container names, and the obsolete version key.

Results appear as you type. Errors are problems that will break docker compose up, while warnings are suggestions that make the file more predictable to run and maintain.

Why Validate Before Running

Compose files fail in two very different ways. Syntax and schema problems stop the run immediately with a cryptic YAML or validation message. Semantic problems are worse: the file starts, but a port collision leaves one service unreachable, a typo in depends_on means your API starts before its database, or a container without a restart policy quietly disappears after a reboot. Catching these before deployment saves a lot of guesswork, and it is exactly the kind of check a CI pipeline should run on every pull request.

How to Use the Validator

1. Paste your docker-compose.yml into the editor, or press Sample to load a working example.
2. Read the verdict card: it reports errors first, then warnings, and says when the file is clean.
3. Work through the issue list from the top. Each entry shows the exact path, such as services.web.ports[0], and the line number for YAML syntax errors.
4. Fix the errors, then address the warnings you care about. The result updates on every keystroke.

Common Errors and What They Mean

• YAML syntax error: almost always an indentation problem. Use spaces, never tabs, and keep sibling keys aligned.
• Missing image or build: a service with neither cannot be created. Add an image reference or a build path.
• Invalid port mapping: strings like 8080:80 are fine, but values such as 8080-80 or 99999:80 are not. Valid forms include 80, 8080:80, 127.0.0.1:8000:80, and 53:53/udp.
• Host port already in use: two services publishing 8080 collide. Change one of the host ports or remove the mapping.
• depends_on references an undefined service: the dependency name must exactly match another key under services.

Best Practices It Flags

• Unpinned images: image: nginx resolves to nginx:latest. Pin nginx:1.27-alpine so builds are reproducible.
• Missing restart policy: long running services should set restart: unless-stopped to survive crashes and reboots.
• privileged: true: grants full host device access and should be reserved for workloads that genuinely need it.
• Fixed container_name: blocks scaling to multiple replicas and makes names collide across projects.
• Obsolete version key: Compose v2 ignores version, so keeping it only causes confusion.

Related Developer Tools

When your compose file builds images from source, generate the Dockerfile with the Dockerfile Generator. If you are converting an existing run command, the Docker Run to Docker Compose Converter produces a first draft. For plain YAML formatting and syntax checks outside Compose, use the YAML Beautifier and YAML Validator.