pip "Defaulting to user installation because normal site-packages is not writeable"

pip noticed it cannot write the global site-packages, so it silently fell back to a user install under ~/.local. The install "succeeds" but packages land somewhere a later step or a different user does not look.

What this error means

pip prints "Defaulting to user installation because normal site-packages is not writeable", reports success, yet a later step fails to import the package or find its script - because it went to ~/.local, not the expected location.

pip output

Defaulting to user installation because normal site-packages is not writeable
Collecting requests
...
Successfully installed requests-2.31.0
# later, running as a different user / in a container layer:
ModuleNotFoundError: No module named 'requests'

Common causes

Global site-packages is not writeable

The job user lacks write access to the system site-packages, so pip quietly switches to a per-user install instead of failing.

User-scoped install invisible elsewhere

Packages in ~/.local are tied to that user and home directory. A different user, a USER switch in a Dockerfile, or a separate home in a later step cannot see them.

How to fix it

Install into a venv to make the location explicit

A venv removes the ambiguity entirely - every step that activates it sees the same packages.

Terminal

python -m venv .venv
. .venv/bin/activate
pip install -r requirements.txt

Keep the install user consistent in Docker

If you intend a user install, set USER before installing and keep it for the run stage so ~/.local matches.

Dockerfile

FROM python:3.12-slim
RUN useradd -m app
USER app
RUN pip install --user -r requirements.txt
# stay as app at runtime so ~/.local resolves

How to prevent it

Use a venv so install location is explicit and shared across steps.
Do not switch users between install and run if relying on --user.
Treat the "Defaulting to user installation" line as a signal to fix the target, not ignore it.