Convert Docker Compose JSON to YAML — Free Browser Converter

Docker Compose expects docker-compose.yaml by default, but Compose itself parses JSON too. If your tooling emits JSON — a custom generator, a CI pipeline, or a migration from another orchestrator — converting to YAML gives you a readable file you can commit. This guide covers the conversion with the quirks specific to Compose: version strings, service dependencies, and environment blocks.

A Real Multi-Service Conversion

Input JSON:

{"version":"3.9","services":{"web":{"image":"nginx:1.25","ports":["80:80"],"depends_on":["api"]},"api":{"image":"node:20","environment":{"DB_HOST":"db","PORT":"3000"}},"db":{"image":"postgres:16","volumes":["pgdata:/var/lib/postgresql/data"],"environment":{"POSTGRES_PASSWORD":"devonly"}}},"volumes":{"pgdata":{}}}

Paste into the converter, click Convert. Output:

version: "3.9"
services:
  web:
    image: nginx:1.25
    ports:
      - "80:80"
    depends_on:
      - api
  api:
    image: node:20
    environment:
      DB_HOST: db
      PORT: "3000"
  db:
    image: postgres:16
    volumes:
      - pgdata:/var/lib/postgresql/data
    environment:
      POSTGRES_PASSWORD: devonly
volumes:
  pgdata: {}

Save as docker-compose.yaml. Run docker compose up -d. Works immediately.

Why YAML for Compose Specifically

Compose is rarely edited in JSON form in 2026. The entire Docker documentation is YAML. Every StackOverflow answer is YAML. Every tutorial, every GitHub example — YAML.

Sticking with JSON creates friction: copy-paste from examples doesn't work directly, diffing is noisier, and new team members have to mentally convert. Convert once, commit YAML, stop fighting the ecosystem.

Sell Custom Apparel — We Handle Printing & Free Shipping

Environment Blocks — List or Map?

Compose accepts two environment syntaxes:

# Map (what JSON naturally produces)
environment:
  DB_HOST: db
  PORT: "3000"

# List (what shell-style configs produce)
environment:
  - DB_HOST=db
  - PORT=3000

Our converter produces the map style because JSON can't represent the list style naturally (a list of strings with = in them). The map style is also more common in modern Compose files.

If you prefer the list style, a find-and-replace after conversion flips it:

s/^  (\w+): (.*)$/  - \1=\2/

Version String Quoting

The Compose file version ("3.9", "3.8") must be a string, not a number. YAML would interpret 3.9 as a float — which breaks Compose.

Our converter preserves quoting from the JSON: if your input has "version":"3.9", output is version: "3.9". If your input has "version":3.9 (a number), output is version: 3.9 — which Compose will reject. Always use a string in your source JSON.

Note: Compose v2 dropped the version field entirely for new files. If you're on modern Compose, you can omit it after conversion.

Post-Conversion Cleanup

Two manual steps worth doing after conversion:

• Drop the version field if you're on Compose v2 (docker compose rather than docker-compose). It's ignored and considered legacy.
• Add comments. YAML comments (#) are the big win over JSON. Document why specific images are pinned to specific tags, or explain non-obvious volume mounts.

Done. Commit the YAML, never touch the JSON again unless you're generating new ones.

Frequently Asked Questions

Does docker compose up work with a JSON file?

Not with the default filename — Compose looks for docker-compose.yaml or docker-compose.yml. You'd need to rename to .json and use the -f flag: docker compose -f compose.json up. Simpler to convert and use the default filename.

Will converting preserve healthcheck and depends_on configurations?

Yes — both are preserved identically. healthcheck's nested structure (test, interval, timeout, retries) maps directly. depends_on lists pass through unchanged.

What about Compose files with extension fields like x-common?

Extension fields (any key starting with x-) are preserved by the converter. Compose uses them for shared config via YAML anchors (&name, *name). After conversion you may want to hand-add anchors.

Can I convert multi-file Compose setups?

Convert each JSON file separately. Compose merges multiple files at runtime with docker compose -f base.yaml -f override.yaml up. The conversion is per-file.