Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Servers, nginx and Docker

A Python virtual environment stops working inside a Docker image

Errorthe container exits at start with: no such file or directory (for the venv's python)

Short answer

A virtual environment is tied to the path and platform it was created on: its scripts hold absolute shebang paths and its python is a link to one interpreter. Do not copy a host .venv into an image. Create the venv inside the image, copy it between stages only at the same path, and put its bin folder on PATH.

  • Applies to Docker Engine 27, Python 3.12, python:3.12-slim images
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Look at what the venv in the container really points to: the python link, the home line in pyvenv.cfg, and the first line of a script.

    docker run --rm --entrypoint sh my-image -c 'ls -l /app/.venv/bin | head; cat /app/.venv/pyvenv.cfg; head -n 1 /app/.venv/bin/pip'
  2. 2Match what you see, then jump to its fix

    1. 1The .venv folder is in the build context, and its python link points to a path or platform that is not in the imageA venv from your laptop was copied into the imageFix
    2. 2The final stage copies the venv, but its python or scripts are missing or refuse to startThe venv was moved to another path or base image in a multi-stage buildFix
    3. 3python works as /opt/venv/bin/python, but plain python or the installed command is not found, or system Python is usedThe venv exists, but its bin folder is not on PATHFix

What does the error look like?

  • the container exits at start with: no such file or directory (for the venv's python)
  • a venv command such as gunicorn is reported as not found

Cause 1 of 3

A venv from your laptop was copied into the image

1Check

A venv holds a copy or symlink of the interpreter it was made with, and the scripts in it carry absolute paths. Both belong to the machine that built it. See whether the context sends your .venv.

ls -d .venv venv 2>/dev/null
cat .dockerignore 2>/dev/null

2Fix

Keep the folder out of the build context, and create the environment inside the image from your requirements file.

# .dockerignore
.venv

# Dockerfile
RUN python -m venv /opt/venv
RUN /opt/venv/bin/pip install -r requirements.txt

3Verify

The interpreter in the image points to a path inside the image.

docker run --rm my-image ls -l /opt/venv/bin/python

Confirmed by docs.astral.sh

Did this fix it?

Cause 2 of 3

The venv was moved to another path or base image in a multi-stage build

1Check

The Python docs say environments are not movable or copyable, because shebang lines hold absolute paths to the environment's interpreter. A stage with a different Python install or a different venv path breaks them.

grep -n "FROM\|venv\|COPY --from" Dockerfile
docker run --rm --entrypoint sh my-image -c 'cat /opt/venv/pyvenv.cfg'

2Fix

Build and run on the same Python base image, create the venv at the final path, and copy that exact path. If anything else moves, recreate the environment.

FROM python:3.12-slim AS build
RUN python -m venv /opt/venv
COPY requirements.txt .
RUN /opt/venv/bin/pip install -r requirements.txt

FROM python:3.12-slim
COPY --from=build /opt/venv /opt/venv

3Verify

The copied environment starts its own interpreter.

docker run --rm my-image /opt/venv/bin/python -c "import sys; print(sys.prefix)"

Confirmed by docs.python.org

Did this fix it?

Cause 3 of 3

The venv exists, but its bin folder is not on PATH

1Check

The uv Docker guide selects the environment by placing its bin directory at the front of PATH with an ENV line, so it applies to every later instruction and to the running container.

docker run --rm my-image sh -c 'echo $PATH; command -v python'

2Fix

Set PATH once with ENV, so every later instruction and the running container use the venv.

ENV PATH="/opt/venv/bin:$PATH"
CMD ["python", "main.py"]

3Verify

python resolves to the venv.

docker run --rm my-image sh -c 'command -v python'

Confirmed by docs.astral.sh

Did this fix it?

How do I stop it coming back?

  • Add .venv to .dockerignore in every Python repo that has a Dockerfile.
  • Treat a venv as disposable: install from requirements.txt inside the image on every build.
  • Use one Python base image and one venv path across all stages.
  • Set ENV PATH to the venv bin folder in the Dockerfile so every later instruction uses it.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.