El error «externally-managed-environment» de pip y la PEP 668

Qué es

error: externally-managed-environment es la respuesta de pip (a partir de pip 23.0) cuando encuentra un archivo marcador EXTERNALLY-MANAGED en el directorio de la biblioteca estándar de la instalación de Python de destino; el bloque de texto que sigue comienza con × This environment is externally managed. Fuera de un entorno virtual, también bloquea pip install --user. La PEP 668 define ese marcador: un distribuidor (una distribución de Linux, pero también conda o un sistema similar) lo coloca para declarar que esa instalación concreta de Python la gestiona algo distinto de pip, por lo que pip no debe instalar, actualizar ni eliminar paquetes en ella directamente. La página de especificaciones de la Python Packaging User Guide documenta el mismo marcador y el comportamiento recomendado para los instaladores. El mensaje es de pip, no de Python; el propio archivo marcador puede incluir el texto con la solución que sugiere el distribuidor, y conviene leerlo antes de aplicar una solución genérica.

Por qué importa

Antes de la PEP 668, un pip install fuera de un entorno virtual podía sobrescribir u ocultar sin avisar un paquete que el gestor de paquetes del sistema operativo también gestiona y del que depende, lo que rompía herramientas del sistema compiladas para una versión concreta. El marcador convierte ese problema en un fallo visible en lugar de una corrupción silenciosa, a costa de romper scripts e imágenes de contenedor que daban por supuesta la posibilidad de instalar globalmente sin restricciones.

Cómo aplicarlo

• Diagnóstico: localiza el marcador con python3 -c "import sysconfig; print(sysconfig.get_path('stdlib'))" y busca EXTERNALLY-MANAGED en ese directorio; su contenido suele indicar la solución preferida de la distribución.
• Soluciones, de la menos a la más invasiva:
  1. Usar un entorno virtual para el proyecto: python3 -m venv .venv && source .venv/bin/activate && pip install ... — aísla por completo las instalaciones del intérprete gestionado y es la solución hacia la que la PEP 668 quiere encaminar a los usuarios.
  2. Instalar una herramienta de línea de comandos independiente con pipx install <tool>, que crea un entorno aislado propio para cada herramienta.
  3. Instalar la versión empaquetada por la propia distribución con su gestor de paquetes (p. ej., apt install python3-<name>) cuando exista.
  4. Solo dentro de un entorno desechable y de un único propósito, creado para una sola tarea (una imagen de contenedor temporal, un paso de CI que no vuelve a usar el intérprete después), forzar la instalación con pip install --break-system-packages ... (pip 23.0.1 o posterior, o PIP_BREAK_SYSTEM_PACKAGES=1) — un último recurso inseguro que puede sobrescribir archivos que pertenecen al gestor de paquetes del sistema, no un indicador que deba añadirse por defecto en todas partes.
• Inseguro o engañoso: eliminar el archivo EXTERNALLY-MANAGED. Silencia el aviso sin aislar nada, y una actualización de la distribución puede volver a crearlo sin más.

Trampas

• Añadir --break-system-packages en un host compartido o de larga duración «para que desaparezca el error» convierte cada instalación futura precisamente en el conflicto que el marcador pretende evitar.
• Suponer que el marcador es un error de pip; es una política deliberada de la distribución que pip respeta.