The python slim image holds only the Debian packages needed to run Python, so pip cannot compile packages that need C headers or a compiler. Installs succeed when a prebuilt wheel exists and fail when pip falls back to a source distribution. Fix it with a build stage that has the tools.
What the official docs say
The Docker Library page for the Python image is direct about this. The slim variant does not contain the common Debian packages found in the default tag. When using it, pip install will work if a suitable built distribution is available, and may fail when installing from a source distribution, because the image lacks the Debian packages needed to compile extension modules.
The page lists the possible solutions: install the needed Debian packages before running pip, or use the default image, which includes the most commonly required packages.
Three ways to fix it, ranked by what ends up in production
| Approach | What ships to production | Notes |
|---|---|---|
| Builder stage with compilers, copy results | No compilers | Cleanest runtime |
| apt install headers in the slim image | Compilers and headers stay | Simple, bigger surface |
| Use the full default image | Large package set | Easiest, largest surface |
The first approach is the one worth learning. Build wheels or a virtual environment in a stage that has gcc and headers, then copy that environment into a slim final stage.
FROM python:3.14-slim AS build
RUN apt-get update && apt-get install -y --no-install-recommends build-essential \
&& rm -rf /var/lib/apt/lists/*
WORKDIR /app
COPY requirements.txt .
RUN python -m venv /opt/venv && /opt/venv/bin/pip install --no-cache-dir -r requirements.txt
FROM python:3.14-slim
COPY --from=build /opt/venv /opt/venv
ENV PATH="/opt/venv/bin:$PATH"
WORKDIR /app
COPY . .
USER 1000
CMD ["python", "app.py"]
Both stages must use the same Python minor version and the same base distribution, because compiled extensions are tied to them. You may still need the runtime shared libraries for what you built, such as a client library, installed in the final stage.
Read the error before guessing
A failure usually names a missing header file or a failed build of a wheel. That tells you the package had no wheel for your platform and Python version. Check whether a newer release of the package ships one before adding build tools. Pinning to an old version of a dependency can be the reason there is no wheel.
Keep the build repeatable
Install from a lockfile or a requirements file with hashes, so a build does not pull a different version tomorrow. Our post on hash checking covers that step in detail, see make pip installs in a Dockerfile repeatable.
Where Safeguard fits
Safeguard scans Python dependencies from your lockfile and builds an SBOM, with reachability analysis to show which vulnerable packages your code actually imports. That helps when a builder stage adds many transitive packages. Run a free scan to see the list.
Quick check
Is the slim image less secure than the default image?
It has fewer packages, which gives scanners and attackers less to work with. The cost is that you assemble the build tools yourself. Slim is not automatically safe, since the app and its dependencies are the same.
Do I need build-essential in the final image?
Usually not. Compile in the builder stage and copy the virtual environment. The final image needs only the shared libraries the compiled code links against.
Sources
Last reviewed: 19 October 2026.
