Diagnose & Fix Docker
Problems Automatically

Features

Everything you need to lint, diagnose, and fix Docker configurations — from static file checks to live container analysis.

Quick Start

npm install -g dockerdoctor

npx dockerdoctor

# Launch interactive mode (default)
dockerdoctor

# Lint just the Dockerfile
dockerdoctor dockerfile

# Check a specific compose file
dockerdoctor compose -c docker-compose.prod.yml

# JSON output for CI
dockerdoctor --json --severity error

# Auto-apply all safe fixes
dockerdoctor --fix

Interactive Mode

Running dockerdoctor with no flags launches interactive mode — a guided wizard that walks you through scanning.

Scan Target

• Scan current directory — check CWD for Docker files
• Scan subdirectories — recursively find Docker projects up to 4 levels deep
• Specify a directory path — enter any custom path
• Docker daemon only — skip file scanning, check running containers and images

Check Selection

Pick All checks or select specific categories: Dockerfile, Compose, Secrets, Line Endings, Dockerignore, Build, Startup, Network, Performance, Image, or Cleanup.

Subdirectory scanning automatically skips node_modules, .git, dist, build, .next, __pycache__, and vendor.

TUI Browser

When results are found, the TUI shows a split-pane view with severity categories on the left and full detail on the right.

Keyboard Shortcuts

The c key extracts only code blocks from fix instructions — dedented and ready to paste directly into your Dockerfile or compose file.

Commands & Flags

Subcommands

Flags

Static Checks No Docker Required

25 checks that analyze your files without needing a running Docker daemon.

Dockerfile — 9 checks

Compose — 7 checks

Secrets — 4 checks

Line Endings — 3 checks

Dockerignore — 2 checks

Runtime Checks Requires Docker

25 checks that inspect your running Docker daemon, containers, and images.

Build — 4 checks

Startup — 4 checks

Network — 4 checks

Performance — 4 checks

Image — 4 checks

Cleanup — 5 checks

Compose Discovery

dockerdoctor automatically finds compose files using a two-pass strategy:

CI/CD Integration

GitHub Actions

- name: Lint Dockerfiles
  run: npx dockerdoctor --ci --severity error

The --ci flag outputs JSON and uses exit codes:

• Exit 0 — no errors found
• Exit 1 — errors found (warnings and info alone don't trigger failure)
• Exit 2 — invalid arguments (bad file path, invalid severity)

Programmatic API

Import and run checks from your own scripts:

import { buildContext, runChecks } from 'dockerdoctor';

const context = await buildContext(process.cwd());
const report = await runChecks(context, {
  categories: ['dockerfile', 'secrets'],
  minSeverity: 'warning',
});

console.log(`Found ${report.summary.errors} errors`);
for (const result of report.results) {
  console.log(`[${result.severity}] ${result.title}: ${result.message}`);
}

Exports