Tutoriales de VPS
Resolver externally-managed-environment de pip con venv o pipx
Si Python del sistema bloquea la instalación, distingue bibliotecas de proyecto, herramientas CLI y paquetes del sistema. Elige venv o pipx y revisa ensurepip e importaciones de servicios.

Al ejecutar pip install -r requirements.txt en el VPS aparece error: externally-managed-environment. Normalmente significa que el gestor de paquetes del sistema mantiene esa instalación de Python y pip no debe modificarla directamente. No suele ser un problema de red, mirror o permisos.
Para un proyecto utiliza su propio venv; para una aplicación de línea de comandos independiente, considera pipx; para componentes del sistema, prioriza apt. Elegir el entorno correcto evita una instalación forzada que después rompa herramientas del sistema u otros proyectos.
Desde el directorio del proyecto, ejecuta:
command -v python3
python3 --version
python3 -m pip --version
python3 -c "import sys; print(sys.executable); print(sys.prefix); print(sys.base_prefix)"
python3 -m pip vincula pip al intérprete elegido, evitando confusión si pip y pip3 apuntan a otra instalación. Si las dos rutas finales coinciden, normalmente no estás en un venv; si difieren, usas un entorno virtual. La ausencia de pip produce No module named pip, otro error distinto.
La especificación de empaquetado de Python usa EXTERNALLY-MANAGED para indicar gestión externa. No significa que Python esté dañado ni que debas borrar el marcador. Ni sudo pip ni pip install --user son soluciones generales para este error.
| Qué necesitas | Dónde instalar | Cómo utilizarlo |
|---|---|---|
| Dependencias de una web, API o proyecto de scripts | El venv del proyecto | Ejecutar con .venv/bin/python |
| Una aplicación CLI independiente | pipx | Usar el ejecutable expuesto por pipx |
| Un componente del sistema empaquetado por la distribución | apt o equivalente | Seguir la documentación de la distribución |
pipx mantiene un entorno aislado y publica los comandos de cada CLI; consulta la guía de aplicaciones de consola de PyPA. No sustituye la instalación de un requirements.txt arbitrario de proyecto.
Para un proyecto Linux existente, entra en el directorio que contiene su requirements.txt de confianza:
python3 -m venv .venv
.venv/bin/python -m pip --version
.venv/bin/python -m pip install -r requirements.txt
.venv/bin/python -m pip check
Si ya existe .venv, revisa intérprete, dependencias y servicios antes de reemplazarlo. Para un entorno nuevo usa una versión compatible con el proyecto, no otra versión mayor solo para lograr la instalación.
Respeta el lockfile o las instrucciones de despliegue. Restaurar un servicio no es motivo para actualizar todos los paquetes: instalar sin errores no garantiza compatibilidad de la aplicación.
La ruta explícita del intérprete funciona sin activar el entorno. La documentación de venv explica que activar cambia principalmente PATH en la sesión actual; llamar directamente a su Python también funciona.
Para trabajar de forma interactiva en Bash o Zsh:
source .venv/bin/activate
python -m pip --version
python -c "import sys; print(sys.executable)"
deactivate
Python y pip deben resolver dentro de .venv. deactivate restaura la configuración de la sesión; no desinstala paquetes ni borra el entorno. Después prueba importaciones, arranque o salud según el proyecto. Un pip check correcto solo comprueba dependencias declaradas, no el funcionamiento del negocio.
Ubuntu o Debian mínimos pueden mostrar ensurepip is not available. Si usas el python3 predeterminado, instala soporte de venv desde su repositorio:
sudo apt update
sudo apt install python3-venv
Después crea el entorno. La guía de Python de Ubuntu también describe python3-full, que incluye soporte de venv. Elige según los componentes que falten; no elimines Python del sistema para instalar dependencias.
Un Python de otro repositorio, compilado, de pyenv o de un panel puede no corresponder a python3-venv. Confirma el intérprete y obtén soporte de la misma procedencia. No cambies el enlace /usr/bin/python3 para adaptar un único proyecto.
Errores de certificado, timeout, versiones incompatibles o compilación de extensiones pertenecen a otra capa. Revisa índice, red, versión de Python, plataforma y dependencias de compilación. Más permisos o borrar el marcador no los resuelve.
En Ubuntu o Debian con pipx en el repositorio, instálalo primero:
sudo apt install pipx
pipx ensurepath
pipx list
Sigue las instrucciones oficiales de la aplicación para pipx install 应用的发行包名. El nombre debe corresponder a un paquete que realmente proporcione una CLI, no a cualquier biblioteca. Tras ensurepath, puede ser necesario reconectar por SSH o abrir otra sesión para que PATH encuentre el comando.
Instalar con pipx no hace importable el paquete desde el Python de una web; son entornos separados. Si el código necesita import una biblioteca, instálala en su venv. Los nombres de paquete del sistema, de PyPI y de importación también pueden diferir; no adivines la orden solo por el módulo ausente.
La activación solo afecta a esa sesión. Otro usuario, una conexión nueva o un servicio no la heredan automáticamente.
Para el proyecto en /srv/myapp, configura el servicio con /srv/myapp/.venv/bin/python, directorio de trabajo, usuario y variables correctos. Una web puede usar su entrada real, como /srv/myapp/.venv/bin/gunicorn, sin suponer que un python sin ruta apunta al entorno correcto.
No trates source .venv/bin/activate como un ejecutable normal en ExecStart de systemd. Consulta la guía de despliegue Python y el diagnóstico de systemd.
Al migrar de VPS, evita copiar simplemente .venv. Puede contener rutas absolutas y archivos específicos de plataforma. Conserva proyecto, dependencias bloqueadas y configuración; recrea el entorno en el destino y verifica el servicio.
Las opciones de instalación de pip definen este interruptor como permiso para modificar Python gestionado externamente. Evita la restricción, pero no aísla proyectos ni garantiza compatibilidad con paquetes de apt.
Usa venv para proyectos, pipx para CLI y paquetes de la distribución para componentes del sistema. Si ya forzaste instalaciones, conserva el registro, identifica herramientas afectadas y planifica la reparación. No desinstales en masa dependencias del sistema que no conoces.
El artículo original registra ocho pruebas con Python 3.14.0 y pip 25.2 en macOS. Un venv temporal instaló e importó un paquete de demostración local y sin red; el intérprete base y otro entorno no pudieron importarlo. La activación y las rutas directas funcionaron y pip check pasó. No se reprodujo el error de gestión externa de Ubuntu ni se probaron apt, pipx, descargas, compilación real o servicios systemd.