composefmt

A Python tool for formatting Docker Compose YAML files. It reorders top-level and service-level keys in a consistent, predefined order while preserving comments, quotes, and structure.

• Features
• Requirements
• Setup
  • Installation (Optional)
  • Configuration (Optional)
• Usage (multiple ways)
• Testing
• Exit Codes

Features

• Reorders top-level and service-level keys in Docker Compose files
• Configure key orders and YAML indentation via a TOML config file
• Preserves comments, quotes, and YAML structure
• Supports files (glob patterns) and stdin piping
• Outputs formatted content to stdout or overwrites files in-place
• Check-mode for verify formatting without modifying files

Requirements

• Python 3.13+
• uv (for dependency management and installation)

For a full list of Python dependencies, see uv tree or check pyproject.toml.

Setup

git clone <repository-url>
cd composefmt
uv sync

Installation (Optional)

Install composefmt as a global tool:

uv tool install .
# or
uv tool install git+https://git.smsvc.net/docker/composefmt.git

Configuration (Optional)

Create a config file at $XDG_CONFIG_HOME/composefmt.toml to customize key orders and YAML indentation.
This is optional: If no configuration file exists or config options are omitted, the builtin defaults will be used (see composefmt/lib/defaults.py).
YAML keys that are not defined in the configuration will be appended in existing order.

# Custom top-level order
top_level_order = [
    "name",
    "services",
    "networks",
    "volumes",
]

# Custom service-level order
service_order = [
    "image",
    "build",
    "ports",
    "volumes",
    "environment",
]

# Custom YAML indentation
yaml_indent = 4

Usage (multiple ways)

# Format files and overwrite in-place
./composefmt/cli.py docker-compose.yml

# Format files and output to stdout
uv run composefmt docker-compose.yml --stdout

# Check if files are formatted (without modifying them)
composefmt docker-compose.yml --check

# Read from stdin (e.g., for piping)
cat docker-compose.yml | composefmt

see --help for further details

Testing

All tests are defined in ./tests/ and can be run via pytest.

Exit Codes

Exit codes are only relevant in check mode (--check).
In all other modes, the script exits with 0.

Code	Meaning
0	No files would be changed
1	One or more files need formatting