Configuration

How docker-doctor resolves and validates its config file.

On this page

File resolution

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

docker-doctor.config.ts
docker-doctor.config.js
docker-doctor.config.mjs
docker-doctor.config.cjs
docker-doctor.config.json
docker-doctor.config.yaml
docker-doctor.config.yml
a "dockerDoctor" key in package.json

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

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

Shape

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

Key	Type	Purpose
`rules`	`Record<string, "error" \| "warning" \| "info" \| "off">`	Override the severity of an individual rule by its full key
`categories`	`Record<Category, "error" \| "warning" \| "info" \| "off">`	Override every rule in a category at once. `"off"` drops all diagnostics in that category
`ignore.files`	`string[]`	Glob patterns for files to exclude from scanning

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

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.

Unknown top-level keys and unknown category names are silently dropped rather than rejected, matching the legacy config schema's behavior. Invalid severities throw a config error with the offending rule/category name.