{"id":8124,"library":"docker-squash","title":"Docker Squash","description":"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.","status":"active","version":"1.2.2","language":"en","source_language":"en","source_url":"https://github.com/goldmann/docker-squash","tags":["docker","container","image","squash","optimization","cli","podman"],"install":[{"cmd":"pip install docker-squash","lang":"bash","label":"Install with pip"}],"dependencies":[{"reason":"Required for interacting with the Docker daemon and performing image operations.","package":"docker","optional":false}],"imports":[{"note":"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.","wrong":"from docker_squash import Squash","symbol":"docker-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."}],"quickstart":{"code":"docker pull ubuntu:latest\ndocker-squash -t ubuntu:squashed ubuntu:latest\ndocker images | grep 'ubuntu'","lang":"bash","description":"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."},"warnings":[{"fix":"Upgrade to Python 3.6 or newer. The current version requires Python 3.6+.","message":"Support for Python 2.7 and Python 3.5 was dropped in `docker-squash` version 1.1.0.","severity":"breaking","affected_versions":"<1.1.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.","message":"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`.","severity":"gotcha","affected_versions":"All versions, especially around 1.0.x"},{"fix":"Upgrade to `docker-squash` version 1.2.2 or newer, where this bug was fixed.","message":"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.","severity":"gotcha","affected_versions":"1.2.1"},{"fix":"Upgrade `docker-squash` to version 1.2.0 or newer to ensure compatibility with Docker 25+ OCI archive format.","message":"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''.","severity":"gotcha","affected_versions":"<1.2.0"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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.","cause":"The `docker-squash` executable is not installed or not in your system's PATH.","error":"docker-squash: command not found"},{"fix":"Upgrade `docker-squash` to version 1.2.2 or later to resolve this bug.","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.","error":"TypeError: unsupported operand type(s) for |: 'set' and 'set'"},{"fix":"Verify that your Docker daemon is running and accessible (`docker ps`). Double-check the image name and tag for correctness (`docker images`).","cause":"The Docker daemon is either not running, or the specified image name/ID and tag could not be found by the Docker daemon.","error":"docker.errors.APIError: 500 Server Error: Internal Server Error ('No such image: ...')"},{"fix":"Upgrade `docker-squash` to version 1.2.0 or later.","cause":"Your version of `docker-squash` is too old to handle the OCI archive format used by Docker daemon versions 25 and newer.","error":"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+)"}]}