Poetry error: externally-managed-environment (tested fix)

The error comes from pip install poetry into the distro Python. Install Poetry in its own venv (or with pipx). Poetry itself does not check the marker: with virtualenvs.create false it writes into the system Python without any error.

On Debian 12+/Ubuntu 23.04+ (and other distros that mark the system Python as externally managed), error: externally-managed-environment comes from pip install poetry, not from Poetry itself. Measured in a fresh debian:trixie-slim container (Python 3.13.5, Poetry 2.5.1); the transcripts ran in order and are unedited.

1. Install Poetry into its own venv

Transcript:

$ pip install poetry 2>&1 | grep -E '^error|externally' | head -2
error: externally-managed-environment
× This environment is externally managed
$ python3 -m venv /opt/poetry && /opt/poetry/bin/pip install -q poetry && ln -s /opt/poetry/bin/poetry /usr/local/bin/poetry && poetry --version
Poetry (version 2.5.1)

The system pip refuses to install into the distro Python (PEP 668). Give Poetry its own virtual environment and link the executable onto your PATH; that is what pipx and the official installer do for you. Do not reach for --break-system-packages: Poetry's own dependencies would then mix with apt-managed packages.

2. virtualenvs.create false installs into the system Python, with no error

Transcript (a pyproject.toml with dependencies = ["six"] and package-mode = false):

$ poetry config virtualenvs.create false && poetry install 2>&1 | tail -4

  - Installing six (1.17.0)

Writing lock file
$ python3 -c 'import six; print(six.__file__)'
/usr/local/lib/python3.13/dist-packages/six.py
$ poetry config virtualenvs.create true && poetry install 2>&1 | tail -3 && poetry run python -c 'import six,sys; print(sys.prefix)'
Package operations: 1 install, 0 updates, 0 removals

  - Installing six (1.17.0)
/root/.cache/pypoetry/virtualenvs/demo-jRz_VYhF-py3.13

Poetry does not enforce the externally-managed marker. With virtualenvs.create false it installed six straight into /usr/local/lib/python3.13/dist-packages of the system Python, with no warning, exactly the kind of write that pip blocks. That can be acceptable in a throwaway Docker image, but on a real machine leave virtualenvs.create at its default true: Poetry then created ~/.cache/pypoetry/virtualenvs/demo-...-py3.13 and poetry run used it. Set poetry config virtualenvs.in-project true if you prefer a .venv next to the project.

Related: pip error: externally-managed-environment, poetry: All attempts to connect failed, uv pip install vs uv add.

Written with AI assistance. Measured on 2026-10-23 in a fresh debian:trixie-slim container with Python 3.13.5 and Poetry 2.5.1. Each transcript was produced by running the commands verbatim. PlainHeaders is our extension; Poetry is free.