A Python virtual environment stops working inside a Docker image
the 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.
Fix it fast
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'2Match what you see, then jump to its fix
- 1
The .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
The 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
python 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
- 1
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/null2Fix
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.txt3Verify
The interpreter in the image points to a path inside the image.
docker run --rm my-image ls -l /opt/venv/bin/pythonConfirmed by docs.astral.sh
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/venv3Verify
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
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
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:
- TaxiDexMy own multi-tenant taxi dispatch SaaS: API, dispatcher portal, driver and passenger apps, and the servers underneath.
- Dispatch ProA real-time logistics platform: Flutter apps, Spring Boot services and a Kafka event pipeline on AWS.
- stegnor.comMy company site: 804 pages from a Python and Jinja generator, with 15 free browser tools.
Related fixes
Servers
pip install confluent-kafka fails because librdkafka/rdkafka.h is missing
pip stops while building confluent-kafka from source
The error means pip is compiling confluent-kafka from source, and the compiler cannot find the librdkafka C headers.
3 causes, each with a fixServers
pip install cryptography tries to compile and fails in a Docker build
fatal error: 'openssl/aes.h' file not found
cryptography ships prebuilt wheels.
3 causes, each with a fixServers
Docker build fails with apk: not found in a Python or Ubuntu image
/bin/sh: 1: apk: not found
apk is the package manager of Alpine Linux only.
2 causes, each with a fixServers
Docker cannot find manage.py or Permission denied on '/manage.py'
PermissionError: [Errno 13] Permission denied: '/manage.py'
The container is looking for manage.py in a directory where the file is not.
3 causes, each with a fixServers
Compose cannot start the service: exec "python manage.py runserver" failed
starting container process caused: exec: "python manage.py runserver
The container runtime was asked to run a program literally named 'python manage.py runserver', including the spaces.
2 causes, each with a fixServers
docker logs prints nothing for a Flask or Python container
the output appears only after the app exits, or in large delayed bursts
docker logs only shows what the process writes to standard output and standard error.
2 causes, each with a fix