DEV Community

Cover image for Announcing docker-image-size-limit: keep an eye on your docker image size
Nikita Sobolev for

Posted on

Announcing docker-image-size-limit: keep an eye on your docker image size

Originally published in my blog:

GitHub logo wemake-services / docker-image-size-limit

🐳 Keep an eye on your docker image size and prevent it from growing too big

docker-image-size-limit Build status codecov Python Version wemake-python-styleguide

Limit your docker image size with a simple CLI command Perfect to be used inside your CI process.

Read the announcing post.


pip install docker-image-size-limit

Or use our Github Action or pre-built docker image.


We support just a single command:

$ disl your-image-name:label 300MiB
your-image-name:label exceeds 300MiB limit by 114.4 MiB


You can specify your image as:

  • Image name: python
  • Image name with tag: python:3.6.6-alpine

You can specify your size as:

  • Raw number of bytes: 1024
  • Human-readable megabytes: 30 MB or 30 MiB
  • Human-readable gigabytes: 1 GB or 1 GiB
  • Any other size supported by humanfriendly

Programmatic usage

You can also import and use this library as python code:

from docker import from_env
from docker_image_size_limit import check_image_size
oversize = check_image_size(from_env(), 'image-name:latest', '1 GiB')
assert oversize < 0, 'Too big image!'  # negative oversize - is a good thing!

My story

It was an early morning. I was drinking my first cup of tea 🍵 and reviewing a pull request from another developer.

It looked pretty well. Just some new python dependencies to generate beautiful reports. And a bunch of new alpine libraries to make sure everything will work.

So, I have merged it without any hesitations.

Several hours later I have found out that our image size increased from ~200 MiB to ~1.5 GiB in size. 💥 This is unacceptable!

So, I have written this script to restrict the maximum image size in the future:


SIZE="$(docker image inspect "$IMAGE" --format='{{.Size}}')"
test "$SIZE" -gt "$LIMIT" && echo 'Limit exceeded'; false

It is just like js size-limit library, but for docker.

And it worked pretty great. Now, our CI would fail on images that are bigger than our $LIMIT. But, do you know that we are using "Blameless environment" method? If something fails, fix it once and for all, including other projects as well. And now I have to distribute this code to all our projects by copy-pasting these four lines. And, of course, it is not how I like my code distribution.

New project

As a result, I open-sourced this script as a standalone python CLI that can be distributed, installed, and used easily:

$ pip install docker-image-size-limit
$ disl your-image-name:label 300MiB
your-image-name:label exceeds 300MiB limit by 1200 MiB

And that's it.

Now, you can be sure that your image size will always be in control. Checkout out the docs for all possible options. And integrate it to your CI not to make the same mistakes I have already fixed. 🔧

Top comments (3)

defman profile image
Sergey Kislyakov

Also, there's a handy tool called dive so you could inspect your layers. It also supports CI :)

defman profile image
Sergey Kislyakov • Edited

Most of your image size would come from the underlying OS (Ubuntu, Debian, Alpine), and Docker handles it pretty well by re-using OS layers when possible (push, pull, building, etc.). So what's the idea of checking your image size?

Btw, I wonder what dependencies added 1.3GB to your images. I guess some of them brought some dev dependencies that could be removed after all dependencies has been installed. Also, I usually see a line in Dockerfiles that removes apt cache. Maybe it makes sense for the Alpine package manager (apk)?

sobolevn profile image
Nikita Sobolev

Thanks for your suggestions.

  1. It will inspect not only your image size, but all the underlying images as well
  2. apk has --no-cache, so it won't store any cache
  3. It was some pretty html/pdf reports generator and all the binary tools that are required for this task