3.1.1.3 Image Runtime Dependencies

Image runtime dependencies are the libraries, interpreters, and system packages an image includes specifically because the application needs them while actually running, as distinct from tools that were only needed to build or compile the application in the first place.

Declaring Runtime Dependencies Explicitly

A Dockerfile typically installs runtime dependencies through the base image's package manager or a language-specific dependency manager, ensuring the exact set of packages the application needs is present in the final image.

FROM python:3.12-slim
RUN apt-get update && apt-get install -y libpq5
COPY requirements.txt .
RUN pip install -r requirements.txt
COPY . .
CMD ["python", "app.py"]

Here, libpq5 is a runtime dependency needed for a PostgreSQL client library to function, separate from the Python packages installed afterward.

Distinguishing Runtime From Build-Time Dependencies

Compilers, development headers, and build tools are often needed only to install or compile certain dependencies, not to run the application afterward — keeping these out of the final runtime image, typically through a multi-stage build, keeps the image smaller and reduces its exposed surface.

FROM python:3.12 AS build
RUN apt-get update && apt-get install -y gcc python3-dev
COPY requirements.txt .
RUN pip wheel -r requirements.txt -w /wheels

FROM python:3.12-slim
COPY --from=build /wheels /wheels
RUN pip install --no-index --find-links=/wheels -r requirements.txt

The final image never includes gcc or python3-dev, since they were only needed to build wheels in the earlier stage.

Verifying Runtime Dependencies Are Sufficient

A useful check after building an image is confirming the application starts and operates correctly using only the runtime dependencies included, without relying on anything that happened to be present during the build but was not explicitly carried into the final image.

docker run --rm myapp:1.0 python -c "import psycopg2"

Why Runtime Dependencies Matter

Correctly identifying and including exactly the runtime dependencies an application needs — no more, no less — keeps images both functional and minimal, avoiding both missing-library failures and unnecessary bloat from dependencies the running application never actually uses.