Hadolint: Lint Dockerfiles from the Command Line

The dirty little secret regarding containers is that it’s not always as easy as you might expect to to be. Case in point, have you ever crafted a Dockerfile by hand, only to have it fail to run? It can be very frustrating. From YAML indentation, using an inappropriate image, improperly using tags, and wrong volume mapping… there are so many issues that can cause Dockerfiles to fail.

That’s why you need linting.

No, I’m not talking about the fluff that builds up in your clothes dryer. I’m talking about the automated checking of code for programmatic and stylistic errors.

Fortunately, linting is done manually, as that would not only be very time-consuming but can also lead to errors on top of errors. It’s like a writer editing their own work… most often they don’t see every error. The same thing holds true with developers. Sometimes you need either a fresh pair of eyes or a tool specifically created for this purpose.

Hadolint mascot

There are plenty of tools out there, some of which are paid services that allow you to upload Dockerfiles (and other bits of code) to have them linted. There are also desktop apps you can use for the purpose of linting. If you prefer the command line, there are plenty of options available, one of which is called Hadolint.

Hadolint is a command line tool that helps you ensure your Dockerfiles follow best practices and parses your Dockerfile into an abstract syntax tree (AST), after which it runs a pre-defined set of rules with the help of ShellCheck (another script analysis tool) to lint the code.

Let’s find out how to use Hadolint to ensure your Dockerfiles are following best practices and aren’t filled with problems you might not be able to see. I’m going to demonstrate on Ubuntu Server 22.04, but Hadolint is available for installation on Linux, macOS, and Windows.

Fortunately, Hadolint isn’t just available to run locally. If you already have Docker installed, you can run the Hadolint container against your Dockerfile. I’ll show you how to do that as well.

First, let’s go the local route.

How to Install Hadolint

Log into your Ubuntu Server instance, and first install ShellCheck with:

Once that is installed, download Hadolint with the command:

Note: Make sure to check the Hadolint download page to ensure you’re downloading the latest version.

Once the file has downloaded, move it (while also renaming it) to a directory in your $PATH with a command such as:

Next, give the file executable permission with:

You can verify it’s working with the command:

If you see the help page printed out, you’re good to go.

Lint your Dockerfile Locally

For testing purposes, I used an old Dockerfile I had just lying around. Create the file with the command:

Paste the following contents into that file:

Save and close the file.

Now, we can lint the file with Hadolint like so:

The output should look something like this:

Dockerfile:3 DL3007 warning: Using the latest is prone to errors if the image will ever update. Pin the version explicitly to a release tag
Dockerfile:9 DL3009 info: Delete the apt-get lists after installing something
Dockerfile:12 DL3015 info: Avoid additional packages by specifying --no-install-recommends
Dockerfile:12 DL3008 warning: Pin versions in apt get install. Instead of apt-get install <package> use apt-get install <package>=<version>

Go through the output and make changes to your Dockerfile as needed. Once you’ve made the changes, re-lint the file and, hopefully, you’ve resolved any issues.

Lint Your Dockerfile with the Hadolint Docker Container

If you don’t want to bother installing Hadolint on your machine, you can always run the containerized version of the tool against your locally stored Dockerfile. Of course, for that, you’ll need Docker installed. If you don’t already have Docker available, here are the quick steps for installing it on Ubuntu Linux:

1. curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg –dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg
2. echo “deb [arch=amd64 signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable” | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
3. sudo apt-get install apt-transport-https ca-certificates curl gnupg lsb-release curl git -y
4. sudo apt-get update
5. sudo apt-get install docker-ce docker-ce-cli containerd.io -y
6. sudo usermod -aG docker $USER
7. Log out and log back in.

With Docker installed, you can easily lint your Dockerfile with the Hadolint Docker container like so:

If you used the same Dockerfile from earlier (without having changed anything), you should see the same output.

And that’s how you can easily lint your Dockerfiles from the command line. To find out more about how to use Hadolint, make sure to look through the help information (using the Hadolint –help command) to see the different options available. But for basic Dockerfile linting, the straight-up Hadolint command works like a charm.