Configuration

File resolution

Unless you pass --config <path>, docker-doctor looks for the first of these, in order, in the scanned directory:

1. docker-doctor.config.ts
2. docker-doctor.config.js
3. docker-doctor.config.mjs
4. docker-doctor.config.cjs
5. docker-doctor.config.json
6. docker-doctor.config.yaml
7. docker-doctor.config.yml
8. a "dockerDoctor" key in package.json

If none of these exist, docker-doctor runs with its built-in defaults.

The .ts form relies on Node.js importing TypeScript directly, which it does by default from 22.18 on. That version is the CLI's supported floor. On an older runtime docker-doctor exits with a message pointing here, so use the YAML or JSON form instead.

npx @docker-doctor/cli@latest . --config ./custom-docker-doctor.config.ts

The path is resolved from the directory you run the command in, not from [dir]. Earlier releases resolved it from the scanned directory; that still works with a warning on stderr.

Shape

// docker-doctor.config.ts
export default {
  rules: {
    "docker-doctor/no-root-user": "error",
  },
  categories: {
    "Image Size": "off",
  },
  ignore: {
    files: ["examples/**/Dockerfile"],
  },
};

The five valid categories keys are Security, Performance, Best Practices, Compose, and Image Size.

ignore.files patterns match paths relative to the scan root: ** crosses directories, while * and ? stay within one path segment. Brace expansion and character classes are not supported. A pattern that ends in / ignores the whole directory, so vendor/ means vendor/**. A leading ./ has no effect. docker-doctor drops ignored files from discovery, so they produce no diagnostics and don't appear in the report's project lists.

docker-doctor never descends into version-control, dependency and cache directories (.git, node_modules, .venv, coverage, dist, .next, .turbo and similar). It also prunes directories matched by ignore.files before walking them: a pattern ending in /**, such as examples/**, skips the whole tree. Directories the current user cannot read are skipped with a warning on stderr instead of failing the scan. build/, out/, target/ and vendor/ are scanned because projects do keep real Dockerfiles there, so add them to ignore.files if yours are vendored.

YAML and JSON configs

If you'd rather stay in YAML (you're writing Compose files anyway), the same shape works as docker-doctor.config.yaml — no package.json or "type": "module" required:

# yaml-language-server: $schema=https://docker-doctor.vercel.app/schema.json
rules:
  "docker-doctor/no-root-user": error
categories:
  "Image Size": "off"
ignore:
  files:
    - "examples/**/Dockerfile"

The yaml-language-server comment gives you autocomplete and validation in editors with the YAML extension. JSON configs get the same via a $schema key:

{
  "$schema": "https://docker-doctor.vercel.app/schema.json",
  "rules": {
    "docker-doctor/no-root-user": "error"
  }
}

The schema at /schema.json is generated from the built-in rule set, so every rule key and category autocompletes with its description.

Typed config

@docker-doctor/cli exports the DockerDoctorConfig type and a defineConfig helper. Which one to use depends on how you run docker-doctor:

Running via npx without installing — use the type with satisfies. Type-only imports are erased when the config loads, so nothing needs to be installed at runtime (install @docker-doctor/cli as a devDependency if you want editor autocomplete):

// docker-doctor.config.ts
import type { DockerDoctorConfig } from "@docker-doctor/cli";

export default {
  rules: {
    "docker-doctor/no-root-user": "error",
  },
} satisfies DockerDoctorConfig;

@docker-doctor/cli installed as a devDependency — defineConfig also works and gives the same autocomplete:

// docker-doctor.config.ts
import { defineConfig } from "@docker-doctor/cli";

export default defineConfig({
  categories: {
    "Image Size": "off",
  },
});

defineConfig is a real runtime import — a config that uses it fails to load when the package isn't installed in the project, so prefer the satisfies form for npx-only projects.

docker-doctor reports unknown rule keys and unknown category names on stderr (Warning: Unknown rule "…" in config, Warning: Unknown category "…" in config), so a typo in a rule or category name doesn't go unnoticed. It drops unknown top-level keys without a warning. An invalid severity throws a config error that names the rule or category.