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
insert_final_newline	--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
insert_final_newline = 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.

Contributions welcome — please file issues for bugs or feature requests.