1.2.2.1 Runtime Dependency Bundling

Runtime dependency bundling is the practice of including, inside a container image, every dependency an application needs while it is actually executing — as opposed to dependencies only needed while building it — so the container can run the application without requiring anything further from the host.

Distinguishing Runtime From Build-Time Dependencies

Not every dependency used while building an application is needed while running it. A compiler, a set of development headers, or build tooling are necessary to produce a binary or compiled asset, but once that asset exists, only its runtime dependencies — shared libraries, an interpreter, configuration files — are required to actually execute it.

FROM node:20 AS build
WORKDIR /app
COPY . .
RUN npm install && npm run build

FROM node:20-alpine
WORKDIR /app
COPY --from=build /app/dist ./dist
COPY package.json ./
RUN npm install --omit=dev
CMD ["node", "dist/server.js"]

The final image bundles only what is needed to run the built application — production dependencies and the compiled output — leaving the build toolchain behind in the discarded build stage.

Why Runtime Bundling Matters for Image Size

Bundling only runtime dependencies keeps images smaller and faster to pull and start, which matters at scale when many containers are being started or replaced frequently, such as during autoscaling or rolling deployments.

docker images myapp

Bundling Native Libraries

Applications that depend on native shared libraries — for example, a Python application using a package with C extensions — need those libraries present in the final runtime image, even if they were only used indirectly during the build.

FROM python:3.12-slim
RUN apt-get update && apt-get install -y libpq5
COPY --from=build /app/wheels /wheels
RUN pip install --no-index --find-links=/wheels -r requirements.txt

Verifying the Bundle Is Complete

A useful check after building a runtime image is confirming the application actually starts and functions using only what was bundled, without any reliance on tools available during the build stage but absent afterward.

docker run --rm myapp:latest node --version
docker run --rm myapp:latest which npm

If a tool needed by the application at runtime is unexpectedly absent, this kind of check reveals it before the image is deployed, rather than after a runtime failure in production.

Runtime Bundling and Portability

Because the runtime image bundles everything the application needs to execute, it can be deployed to any host capable of running containers, without that host needing to separately install or configure any of the application's dependencies.