Maaz Zindani

Loading the index…

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

The pip root user warning during a Docker build

ErrorWARNING: Running pip as the 'root' user

Short 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.

  • Applies to pip 25, Python 3.13, Docker Engine 28
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 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_ACTION
  2. 2Match what you see, then jump to its fix

    1. 1The warning appears on a server or workstation, not in a throwaway imagePackages go into the system Python on a real machineFix
    2. 2The warning shows in every docker build step that runs pipA container image where root is intendedFix

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.txt

3Verify

pip no longer prints the warning, and sys.prefix points at .venv.

python -c "import sys; print(sys.prefix)"

Confirmed by docs.python.org

Did this fix it?

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-action

2Fix

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=ignore

3Verify

Rebuild; the install step no longer prints the warning.

docker build --no-cache -t my-app .

Confirmed by pip.pypa.io

Did this fix it?

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:

Related fixes

Next step

Want this handled for good?

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