hadolint-pre-commit

A pre-commit hook for hadolint that automatically downloads and installs the hadolint binary — no manual installation required.

Background

The official hadolint/hadolint repository provides a pre-commit hook configuration, but it does not auto-install the hadolint binary. Users who add it to their .pre-commit-config.yaml are met with:

Executable `hadolint` not found

This is a known, long-standing issue that affects everyone who tries to use hadolint as a zero-dependency pre-commit hook. The official hook assumes you have already installed hadolint separately (e.g. via brew install hadolint), which defeats the purpose of a self-contained pre-commit integration.

This project solves that problem. It distributes the official, pre-built hadolint binary through PyPI as a platform-specific wheel. When pre-commit sets up the hook environment, it runs pip install hadolint-py automatically — and your binary is ready to use.

Usage

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

repos:
  - repo: https://github.com/shenxianpeng/hadolint-pre-commit
    rev: v2.15.1.1
    hooks:
      - id: hadolint

Run pre-commit install and the hadolint binary will be downloaded and installed automatically. That's it.

Passing arguments

You can pass any hadolint CLI argument via the args key:

repos:
  - repo: https://github.com/shenxianpeng/hadolint-pre-commit
    rev: v2.15.1.1
    hooks:
      - id: hadolint
        args: [--ignore, DL3008, --ignore, DL3009]

Using a configuration file

hadolint supports a .hadolint.yaml file in your project root. Create it alongside your Dockerfiles:

# .hadolint.yaml
ignore:
  - DL3008  # Pin versions in apt-get install
  - DL3009  # Delete the apt-get lists after installing

failure-threshold: warning
trustedRegistries:
  - docker.io
  - gcr.io

When a .hadolint.yaml is present, hadolint picks it up automatically — no extra args needed.

How it works

This package ships the hadolint binary via PyPI using setuptools-download. When pip install hadolint-py is run (which pre-commit does automatically), the appropriate pre-built binary for your platform is downloaded from the official hadolint GitHub releases and placed in your environment's bin/ directory (or Scripts/ on Windows).

Supported platforms

Comparison with alternatives

Install as a standalone tool

You can also use hadolint-py outside of pre-commit as a standalone CLI tool:

pip install hadolint-py
hadolint --version
hadolint Dockerfile

Versioning

The PyPI version is derived automatically from the release tag (e.g. tag v2.15.1.1 → PyPI version 2.15.1.1) — reference the matching rev: in your .pre-commit-config.yaml. See CONTRIBUTING.md for the release process.

Contributing

Contributions are welcome! Please open an issue or pull request on GitHub.

License

MIT