Jupyter install "error: externally-managed-environment" on Debian/Ubuntu (tested)

pip install jupyterlab (or jupyter, notebook) on Debian 12+/Ubuntu 23.04+ stops with error: externally-managed-environment, and --user or python3 -m pip fail the same way. Install Jupyter into a virtual environment instead; reproduced and fixed below.

1. Reproduce: installing Jupyter on Debian's Python

run.sh runs in a fresh debian:trixie-slim container (Debian 13, the same on Ubuntu 23.04+), installs the distro python3-pip, and tries to install JupyterLab with pip, then with a virtual environment:

#!/bin/sh
# Debian 13 (trixie) with the distro Python: install Jupyter three ways
apt-get update -qq >/dev/null && apt-get install -y -qq python3-pip python3-venv >/dev/null 2>&1
python3 --version
echo '== 1. pip install jupyterlab'
pip install -q jupyterlab 2>&1 | head -3; echo "exit status: $(pip install -q jupyterlab >/dev/null 2>&1; echo $?)"
echo '== 2. pip install --user jupyterlab'
pip install --user -q jupyterlab 2>&1 | head -1
echo '== 3. python3 -m pip install jupyterlab'
python3 -m pip install -q jupyterlab 2>&1 | head -1
echo '== 4. venv'
python3 -m venv /opt/jupyter
/opt/jupyter/bin/pip install -q jupyterlab 2>&1 | tail -2
/opt/jupyter/bin/jupyter lab --version
echo '== 5. which python the notebook kernel runs'
/opt/jupyter/bin/jupyter kernelspec list
/opt/jupyter/bin/python -c "import sys; print(sys.executable)"
echo '== 6. %pip install inside that kernel = the venv pip'
/opt/jupyter/bin/python -m pip install -q six && /opt/jupyter/bin/python -c "import six; print('six', six.__version__)"

Output:

Python 3.13.5
== 1. pip install jupyterlab
error: externally-managed-environment

× This environment is externally managed
exit status: 1
== 2. pip install --user jupyterlab
error: externally-managed-environment
== 3. python3 -m pip install jupyterlab
error: externally-managed-environment
== 4. venv
4.6.4
== 5. which python the notebook kernel runs
Available kernels:
  python3    /opt/jupyter/share/jupyter/kernels/python3
/opt/jupyter/bin/python
== 6. %pip install inside that kernel = the venv pip
six 1.17.0

2. What it means

The distro marks its Python as externally managed (PEP 668), so pip refuses to install into it: plain pip install, --user, and python3 -m pip all fail the same way, with exit status 1, before anything is downloaded. It is not a Jupyter problem; any package gives the same error (see pip "externally-managed-environment").

3. Fix: put Jupyter in a venv

• python3 -m venv ~/jupyter (needs python3-venv), then ~/jupyter/bin/pip install jupyterlab and start it with ~/jupyter/bin/jupyter lab. In the test this installed JupyterLab 4.6.4 with no error.
• The default python3 kernel then lives inside the venv, so %pip install in a notebook installs into the venv too, and is not blocked (step 6 above).
• To use another project's environment as a kernel, install ipykernel in that environment and register it; if a kernel then won't start, see Jupyter "Error Starting Kernel".
• --break-system-packages also silences the error but installs into the distro Python, which the error message itself warns can break the OS's Python; prefer the venv.

Related: externally-managed-environment in Docker, Jupyter kernel not found.

Written with AI assistance. Measured on 2026-10-23 in a debian:trixie-slim container (Python 3.13.5, JupyterLab 4.6.4). The script ran verbatim and the output was pasted unedited. PlainTables is our extension; Jupyter is free.