dockerfmt

An opinionated Dockerfile formatter. Formats directives, normalizes whitespace, and uses shfmt to format shell commands inside RUN steps.

Spiritual successor to dockfmt, built on the buildkit parser.

Table of Contents

• Demo
• Features
• Installation
• Usage
• Configuration
• Ignoring Directives
• Pre-commit
• Limitations

Demo

MAINTAINER me
FROM node:lts-alpine          as       builder

COPY        .      /app WORKDIR         /app ENV MY_VAR my-value ENV a=1 \   b=2 \             c=3 RUN apt-get update && \     # install deps     apt-get install -y --no-install-recommends \         vim curl git && \     apt-get clean && \     rm -rf /var/lib/apt/lists/* \     && find /tmp -not -path /tmp -delete

LABEL org.opencontainers.image.authors="me"
FROM node:lts-alpine as builder
COPY . /app WORKDIR /app ENV MY_VAR=my-value ENV a=1 \     b=2 \     c=3 RUN apt-get update \     # install deps     && apt-get install -y --no-install-recommends \         vim curl git \     && apt-get clean \     && rm -rf /var/lib/apt/lists/* \     && find /tmp -not -path /tmp -delete

Features

• Formats shell commands in RUN steps via shfmt — consistent && chains, indentation, quoting
• Preserves and re-aligns inline comments, even across multiline RUN steps
• Normalizes whitespace and extra blank lines across all directives
• Converts legacy ENV syntax (ENV key value → ENV key=value)
• Upgrades deprecated directives (MAINTAINER → LABEL)
• Supports heredocs in RUN steps
• Reads from files or stdin
• Pre-commit hook support
• JS/WASM bindings for Node.js (docs)
• Docker image for CI use

Installation

Binaries

Download from the releases page.

go install

go install github.com/reteps/dockerfmt@latest

Docker

docker run --rm -v $(pwd):/pwd ghcr.io/reteps/dockerfmt:latest /pwd/Dockerfile

Usage

# format and print to stdout
dockerfmt Dockerfile
format in place
dockerfmt -w Dockerfile
read from stdin
cat Dockerfile | dockerfmt
check if already formatted (exits non-zero if not)
dockerfmt -c Dockerfile

Usage:
  dockerfmt [Dockerfile...] [flags]
  dockerfmt [command]
Available Commands:   completion  Generate the autocompletion script for the specified shell   help        Help about any command   version     Print the version number of dockerfmt
Flags:   -c, --check             Check if the file(s) are formatted   -h, --help              help for dockerfmt   -i, --indent uint       Number of spaces to use for indentation (default 4)   -n, --newline           End the file with a trailing newline   -s, --space-redirects   Redirect operators will be followed by a space   -w, --write             Write the formatted output back to the file(s)

Configuration

EditorConfig

dockerfmt reads EditorConfig files to pick up project-level formatting defaults. The following properties are supported:

| EditorConfig property | dockerfmt equivalent | Notes | | ------------------------ | -------------------- | --------------------------- | | indent_size | --indent | Standard EditorConfig key | | insertfinalnewline | --newline | Standard EditorConfig key | | space_redirects | --space-redirects | Custom key (non-standard) |

CLI flags always take precedence over EditorConfig values.

Example .editorconfig:

[Dockerfile]
indent_size = 2
insertfinalnewline = true

Note: EditorConfig is only applied when formatting files by path.

It is not used when reading from stdin, since there is no file path to resolve against.

Ignoring Directives

To skip formatting for a specific directive, place a # dockerfmt-ignore comment on the line immediately before it:

# dockerfmt-ignore
RUN   echo   "this stays exactly as-is"
RUN echo "this gets formatted normally"

The ignore comment applies only to the next directive. This is useful as an escape hatch for cases where the formatter produces unwanted output, such as command grouping or unescaped semicolons:

# dockerfmt-ignore
RUN { echo hello && echo world; }
dockerfmt-ignore
RUN echo hello; echo world

Pre-commit

Add to your .pre-commit-config.yaml:

repos:
  - repo: https://github.com/reteps/dockerfmt
    rev: main  # run pre-commit autoupdate to pin a version
    hooks:
      - id: dockerfmt
        args:
          - --indent=4
          - --newline
          - --write

Limitations

• The RUN formatter does not support command grouping ({ \) or unescaped semicolons — these are returned unformatted.
• The # escape=X parser directive is not supported.
• No line wrapping for long JSON-form commands.