Introduction

pipenv works fine in Docker, but the cleanest container pattern is different from the usual local-development pattern. In most Docker images you do not want pipenv shell; you want pipenv to install locked dependencies into the container's system Python during the image build.

The Practical Docker Pattern

Inside a container, the container itself is already an isolated environment. Because of that, pipenv install --system --deploy is usually the right choice.

1FROM python:3.12-slim
2
3WORKDIR /app
4
5RUN pip install --no-cache-dir pipenv
6
7COPY Pipfile Pipfile.lock ./
8RUN pipenv install --system --deploy --ignore-pipfile
9
10COPY . .
11
12CMD ["python", "app.py"]

This does four important things:

• installs pipenv,
• copies Pipfile and Pipfile.lock before the rest of the source for layer caching,
• installs exactly the locked dependencies,
• and runs the app with the container's Python instead of launching a nested virtual environment.

Why --system Is Usually Better in Docker

Without --system, pipenv creates a virtual environment inside the container. That is not inherently wrong, but it adds an extra environment layer inside something that is already isolated by Docker.

Using --system keeps the image simpler:

• fewer moving pieces,
• easier CMD lines,
• and less confusion about where packages were installed.

If you truly want a project-local virtual environment inside the image, you can do it, but it is a specialized choice rather than the default best practice.

Build Caching Matters

A slow Docker build is often caused by copying the whole application too early. If you copy the entire source tree before dependency installation, any code change invalidates the dependency layer.

This order is better:

COPY Pipfile Pipfile.lock ./
RUN pipenv install --system --deploy --ignore-pipfile
COPY . .

With that layout, application code changes do not force a full dependency reinstall unless the lock file changed.

Development vs Production Images

For local development in Docker, you may want development dependencies too:

RUN pipenv install --system --deploy --dev

For production, keep it stricter and smaller:

RUN pipenv install --system --deploy --ignore-pipfile

The --deploy flag causes the build to fail if the lock file is missing or out of sync. That is valuable in CI because it prevents "works on my machine" dependency drift.

A Small Example Project

Suppose your Pipfile defines Flask:

1[[source]]
2url = "https://pypi.org/simple"
3verify_ssl = true
4name = "pypi"
5
6[packages]
7flask = "*"
8
9[requires]
10python_version = "3.12"

A minimal app can then be:

1from flask import Flask
2
3app = Flask(__name__)
4
5@app.get("/")
6def index():
7    return {"status": "ok"}
8
9if __name__ == "__main__":
10    app.run(host="0.0.0.0", port=8000)

Build and run it:

docker build -t pipenv-demo .
docker run --rm -p 8000:8000 pipenv-demo

At that point, pipenv is only part of the build workflow. The running container just executes Python normally.

Multi-Stage Builds Are Optional but Useful

If your project compiles native dependencies, a multi-stage build can reduce final image size by separating the build environment from the runtime environment. The idea is to install dependencies in one stage and copy the results into a smaller runtime image.

That is not mandatory for every project, but it becomes attractive when the base image would otherwise carry build tools you do not need at runtime.

Common Pitfalls

The most common mistake is trying to run pipenv shell inside Docker. That opens an interactive shell, which is not how container startup is normally managed.

Another mistake is omitting Pipfile.lock from the image build. Without the lock file, you lose reproducibility and may install different dependency versions between builds.

Developers also often skip --system and then wonder why the container cannot find packages when CMD ["python", "app.py"] runs. The packages may be inside a virtual environment that the process never activated.

Finally, if the image rebuilds dependencies on every code change, check the COPY order. Docker layer caching only helps when the dependency files are copied separately.

Summary

• In Docker, the usual pipenv pattern is pipenv install --system --deploy.
• Copy Pipfile and Pipfile.lock before application code to preserve layer caching.
• Use --ignore-pipfile in production builds when you want the lock file to be the source of truth.
• Do not rely on pipenv shell as the container startup model.
• Treat pipenv as a build-time dependency manager and let the container run plain Python.