Dockerfile: Use pip –no-cache-dir to Reduce Image Size

This page describes a highlighted problem produced by the Docker and Kubernetes Security scanner plugin.

You could find more details on the internal page: Cloud (IaC) Security plugin

If this project has been helpful to you, please consider giving it a ⭐ on GitHub to help others discover it.

What’s the problem with pip cache?

The pip package manager stores cached wheels, source distributions, and metadata in ~/.cache/pip/ to speed up subsequent installations. While this pip cache is beneficial for local development environments, it becomes dead weight in Docker images, potentially increasing image size by hundreds of megabytes. In containerized environments, cached package data from pip can dramatically bloat images if not properly managed with --no-cache-dir flags.

The Docker Layer Problem

Docker images consist of immutable layers where each Dockerfile instruction creates a new layer. When you install Python packages and clean the cache in separate RUN commands, the cache persists in intermediate layers even after deletion. This occurs because each layer contains only the differences from the previous layer, and deleted files in subsequent layers don’t remove them from earlier layers – they simply mark them as hidden.

Disabling pip Cache With –no-cache-dir

The critical optimization technique involves using the --no-cache-dir flag with pip install commands. This approach ensures that no cache is created during package installation, preventing unnecessary data from being stored in Docker image layers.

Problematic code

FROM python:3.9
USER nobody
RUN pip install django
RUN pip install -r requirements.txt

Verified code

FROM python:3.9
USER nobody
RUN pip install --no-cache-dir django
RUN pip install --no-cache-dir -r requirements.txt

The --no-cache-dir flag is essential for production Docker images and ensures minimal image size. This practice is particularly important when building images in CI/CD pipelines, where pip cache provides no benefit for subsequent builds.

Alternative Solutions To Disable Pip Cache

While the --no-cache-dir flag is the most straightforward approach. There are several alternative methods to disable pip caching in Docker environments.

Disable Pip Cache with Environment Variable

You can set the PIP_NO_CACHE_DIR environment variable in your Dockerfile to globally disable caching for all pip operations:

FROM python:3.9
ENV PIP_NO_CACHE_DIR=1
USER nobody
RUN pip install django
RUN pip install -r requirements.txt

This approach is particularly useful when you have multiple pip install commands throughout your Dockerfile, as it eliminates the need to add --no-cache-dir to each individual command.

Disable Pip Cache with Configuration File

For a more permanent configuration, you can create a pip configuration file that disables caching. Create a pip.conf file and copy it into your Docker image:

# pip.conf
no-cache-dir = true
# Dockerfile
FROM python:3.9
COPY pip.conf /etc/pip.conf
USER nobody
RUN pip install django
RUN pip install -r requirements.txt

Alternatively, you can create the configuration inline:

FROM python:3.9
RUN mkdir -p /etc/pip && \
    echo "[global]\nno-cache-dir = true" > /etc/pip/pip.conf
USER nobody
RUN pip install django
RUN pip install -r requirements.txt