docker-compose-linter#

A pure Python 3 (stdlib only) linter for docker-compose.yml files.

Commands#

text

python3 scripts/docker-compose-linter.py <command> [options] FILE

CommandDescriptionlintLint a docker-compose.yml for issuesservicesList all services with their images/buildsportsList all port mappings, detect conflictsauditFull audit (lint + services + ports summary)

Options#

OptionDescription--format text|json|markdownOutput format (default: text)--strictExit 1 on any issue (not just errors)--ignore RULEIgnore a specific rule (repeatable)--min-severity error|warning|infoMinimum severity to report (default: info)

Lint Rules#

RuleSeverityDescriptionno-versioninfoMissing or outdated version: keyno-healthcheckwarningService without healthcheck definedno-restart-policywarningService without restart policyprivileged-modeerrorService running in privileged modeport-conflicterrorMultiple services mapping to same host porthost-networkwarningUsing network_mode: host (security risk)latest-tagwarningImage using :latest tag or no tagno-resource-limitsinfoNo memory/CPU limits (deploy.resources)hardcoded-envwarningSecrets/passwords directly in environment variablesroot-userwarningNo user: specified (runs as root by default)missing-depends-oninfoService uses links but no depends_onbind-mount-relativeinfoRelative bind mount pathsno-logginginfoNo logging configurationduplicate-serviceerrorDuplicate service names

Examples#

bash

# Lint with default text output
python3 scripts/docker-compose-linter.py lint docker-compose.yml

# Only show errors and warnings
python3 scripts/docker-compose-linter.py --min-severity warning lint docker-compose.yml

# JSON output for CI pipelines
python3 scripts/docker-compose-linter.py --format json lint docker-compose.yml

# Full audit in markdown
python3 scripts/docker-compose-linter.py --format markdown audit docker-compose.yml

# Ignore specific rules
python3 scripts/docker-compose-linter.py --ignore root-user --ignore no-logging lint docker-compose.yml

# Strict mode: exit 1 on any issue
python3 scripts/docker-compose-linter.py --strict lint docker-compose.yml

Requirements#

• Python 3.7+
• No external dependencies (pure stdlib)