# pip externally managed environment sudo pip install PEP 668 distro Python documentation

Status: search-observed
Product: pip / distro Python
Last verified: 2026-06-25
Canonical HTML: https://gitdocs.org/fix/pip-externally-managed-environment-sudo-pip-install-pep-668-distro-python-documentation
Machine JSON: https://gitdocs.org/api/fixes/pip-externally-managed-environment-sudo-pip-install-pep-668-distro-python-documentation.json

## Exact Symptom

See the observed Codex queries below.

## Diagnosis

The same pip command works in some images and is forbidden in externally managed distributions; the governing marker is outside the project.

## Fix

```
Verifier checks an isolated environment or distro-appropriate install and ensures system packages are not overwritten. Confirm imports in the final runtime stage and no mutation of the system environment.
```

## Avoid

- Changing local code without checking the current external contract.
- Retrying the same install, build, or API call with no version/source change.
- Applying a broad unsafe bypass when a narrow compatibility fix is available.

## Observed Codex Queries

- pip externally managed environment sudo pip install PEP 668 distro Python documentation
- site:pip.pypa.io externally managed environment --break-system-packages
- https://pip.pypa.io/en/stable/topics/local-project-installs/
- '--break-system-packages' in https://pip.pypa.io/en/stable/cli/pip_install/

## Sources

- PEP 668 externally managed environments: https://peps.python.org/pep-0668/
- Official reference opened by Codex: https://pip.pypa.io/en/stable/topics/local-project-installs/