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

pip could not write to the interpreter’s global site-packages, so it quietly fell back to a per-user install under ~/.local. The package installs, but its console scripts and modules land somewhere the rest of the job may not look.

What this error means

pip prints "Defaulting to user installation because normal site-packages is not writeable" and succeeds - yet a later step can’t find the installed command or import the package, because it went to ~/.local for a different user than the one running later.

pip output

Defaulting to user installation because normal site-packages is not writeable
Collecting black
  ...
Successfully installed black-24.4.2
$ black --version
black: command not found

Common causes

Global site-packages is root-owned

The interpreter’s site-packages belongs to root (or another user) and the job runs unprivileged, so pip can’t write there and falls back to the user scheme.

User-install scripts dir not on PATH

A user install puts console scripts in ~/.local/bin, which is often absent from PATH in CI, so the command "isn’t found" even though it installed.

How to fix it

Install into a virtual environment

A venv is writable by the job user and keeps scripts on a predictable PATH, removing the fallback entirely.

Terminal

python3 -m venv .venv
. .venv/bin/activate
pip install -r requirements.txt   # no user fallback

Put the user scripts dir on PATH

If you intentionally use a user install, add its bin directory to PATH for later steps.