The pip root user warning during a Docker build
WARNING: Running pip as the 'root' userShort answer
pip prints this warning whenever it runs as root, because installing into the system Python can clash with the operating system's own packages. In a Docker image you can accept that on purpose and set pip's root user action to ignore, or avoid it by installing into a virtual environment.
Fix it fast
1Find out which cause you have
Confirm who runs pip in the build, and whether pip is already set to ignore the check.
id -u pip config list env | grep PIP_ROOT_USER_ACTION2Match what you see, then jump to its fix
What does the error look like?
WARNING: Running pip as the 'root' user
Cause 1 of 2
Packages go into the system Python on a real machine
1Check
A virtual environment keeps its own independent set of packages in its own site directory.
which python && python -c "import sys; print(sys.prefix)"2Fix
Create a virtual environment and install into it as a normal user.
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt3Verify
pip no longer prints the warning, and sys.prefix points at .venv.
python -c "import sys; print(sys.prefix)"Confirmed by docs.python.org
Cause 2 of 2
A container image where root is intended
1Check
pip has a documented option for what to do when it runs as root: warn (the default) or ignore.
pip install --help | grep -A1 root-user-action2Fix
Set the action to ignore, either per command or for the whole image through the environment variable.
# per command
RUN pip install --root-user-action=ignore -r requirements.txt
# or for the whole image
ENV PIP_ROOT_USER_ACTION=ignore3Verify
Rebuild; the install step no longer prints the warning.
docker build --no-cache -t my-app .Confirmed by pip.pypa.io
How do I stop it coming back?
- Use a multi-stage build with a venv, then copy the venv into a slim final image.
- Run the final container as a non-root user.
- Keep ignore for images only; do not set it on shared servers.
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