Docker Squash

1.2.2 · active · verified Thu Apr 16

docker-squash is a Python utility that reduces Docker image sizes by combining multiple layers into one. It retains Dockerfile metadata such as `PORT` and `ENV` instructions, which the native `docker build --squash` command often discards. The project is actively maintained with regular updates, currently at version 1.2.2.

Common errors

```
docker-squash: command not found
```
cause The `docker-squash` executable is not installed or not in your system's PATH.

fix Ensure the library is installed with `pip install docker-squash` and that your Python environment's scripts directory is included in your system's PATH. If using a virtual environment, activate it.
```
TypeError: unsupported operand type(s) for |: 'set' and 'set'
```
cause This error specifically occurred due to a regression in `docker-squash` version 1.2.1 when attempting to use the `-f` or `--from-layer` flag.

fix Upgrade `docker-squash` to version 1.2.2 or later to resolve this bug.
```
docker.errors.APIError: 500 Server Error: Internal Server Error ('No such image: ...')
```
cause The Docker daemon is either not running, or the specified image name/ID and tag could not be found by the Docker daemon.

fix Verify that your Docker daemon is running and accessible (`docker ps`). Double-check the image name and tag for correctness (`docker images`).
```
Failed to load image: No such file or directory: 'scratch/old/blobs/layer.tar' (or similar file-not-found errors during squashing with Docker 25+)
```
cause Your version of `docker-squash` is too old to handle the OCI archive format used by Docker daemon versions 25 and newer.

fix Upgrade `docker-squash` to version 1.2.0 or later.

Warnings

breaking Support for Python 2.7 and Python 3.5 was dropped in `docker-squash` version 1.1.0.
Fix: Upgrade to Python 3.6 or newer. The current version requires Python 3.6+.
gotcha The `docker-squash` utility has had varying compatibility requirements with the underlying Docker Python client library (PyPI package `docker`). Earlier versions (e.g., 1.0.7) pinned the client to `<3` due to performance issues, while later versions (e.g., 1.0.10) added support for `>=6.0.0`.
Fix: Ensure your installed `docker` Python package version is compatible with your `docker-squash` version. Refer to the `docker-squash` changelog or PyPI dependencies for the specific range supported by your version.
gotcha Version 1.2.1 introduced a regression that prevented the `-f` (from-layer) flag from working correctly. This caused squashing operations using this flag to fail.
Fix: Upgrade to `docker-squash` version 1.2.2 or newer, where this bug was fixed.
gotcha Older versions of `docker-squash` (prior to 1.2.0) were incompatible with Docker daemon versions 25 and newer, due to Docker 25 switching to the OCI archive format. This could lead to errors like 'No such file or directory: 'scratch/old/blobs/layer.tar''.
Fix: Upgrade `docker-squash` to version 1.2.0 or newer to ensure compatibility with Docker 25+ OCI archive format.

Install

pip install docker-squash Install with pip

Imports

docker-squash
wrong:
```
from docker_squash import Squash
```
correct:
```
This library is primarily a command-line interface (CLI) tool. It is typically invoked directly from the shell rather than imported and used programmatically in Python code.
```
While there's internal Python code, the public-facing and documented usage is via the 'docker-squash' CLI command. Direct programmatic import is not officially supported or commonly practiced.

Quickstart

This quickstart demonstrates how to pull a base Ubuntu image and then use `docker-squash` to squash its layers into a new image tagged `ubuntu:squashed`. The final command lists Docker images, allowing you to compare the original and squashed image sizes.

docker pull ubuntu:latest
docker-squash -t ubuntu:squashed ubuntu:latest
docker images | grep 'ubuntu'

view raw JSON →