autohooks-plugin-hadolint

An autohooks plugin for Dockerfile linting via hadolint.

On git commit the plugin runs hadolint against every staged Dockerfile. If hadolint reports a violation the commit is aborted and the findings are printed.

Installation

Install the plugin

Using uv (recommended):

uv add --dev autohooks-plugin-hadolint

Using pip:

python3 -m pip install --user autohooks-plugin-hadolint

Install hadolint

hadolint is a standalone binary and not a Python package, so it is not installed as a dependency of this plugin. Pick whichever route suits you:

brew install hadolint

sudo apt-get install hadolint

Or download a release binary from hadolint/hadolint and put it on your PATH.

You can also skip the local install entirely and run hadolint through Docker — see Running hadolint from a container.

Usage

Activate the plugin:

uv run autohooks plugins add autohooks.plugins.hadolint

or add it to your pyproject.toml directly:

[tool.autohooks]
mode = "uv"
pre-commit = ["autohooks.plugins.hadolint"]

and install the git hook itself:

uv run autohooks activate --mode uv

Configuration

All settings live under [tool.autohooks.plugins.hadolint] in your pyproject.toml. Every key is optional.

Each key also accepts a bare string instead of a list.

Running a local binary

[tool.autohooks.plugins.hadolint]
command = ["hadolint"]
arguments = ["--no-color", "--format", "tty", "--failure-threshold", "warning"]

Running hadolint from a container

The plugin passes each Dockerfile as a path relative to the project root, so mounting the root into the container is all that is needed. Use the {root} placeholder for the mount source:

[tool.autohooks.plugins.hadolint]
command = [
    "docker", "run", "--rm",
    "-v", "{root}:/repo", "-w", "/repo",
    "hadolint/hadolint", "hadolint",
]

The same works for podman or a wrapper script — the first element of command is what the plugin checks for on your PATH.

hadolint's own configuration

Rules are configured by hadolint itself, for example through a .hadolint.yaml in the repository root:

ignored:
  - DL3008

When running from a container, make sure the config file is inside the mounted directory (it is, with the {root} mount above).

Example

Copy examples/binary or examples/docker into a git repository of its own and follow examples/README.md to watch a commit get rejected and then pass.

Contributing

Contributions are welcome. Please open a pull request on GitHub — for larger changes, please open an issue first so the approach can be discussed.

Development setup

The project uses uv:

uv sync

Run the tests:

uv run pytest

One test exercises the real hadolint binary and is skipped when hadolint is not on your PATH, so install it to run the full suite.

Lint and format with ruff:

uv run ruff check . && uv run ruff format .

The repository uses its own hooks — ruff and this plugin run on every commit. Install them once with:

uv run autohooks activate --mode uv

License

Copyright (C) 2026 Muthu Kumaran R

Licensed under the GNU General Public License v3.0 or later.