ensurepip en Python: restaura pip

El módulo ensurepip en Python instala o restaura pip usando componentes incluidos con el intérprete. No accede a Internet. Su objetivo es hacer bootstrap del instalador cuando la configuración omitió esa etapa, cuando pip fue eliminado o cuando un entorno necesita recuperar una versión mínima funcional.

La mayoría de usuarios no necesita invocarlo porque los instaladores oficiales y venv suelen incluir pip. Algunas distribuciones Linux separan o desactivan el módulo. En ese caso, sigue las instrucciones del proveedor de Python en lugar de forzar cambios en el entorno gestionado por el sistema operativo.

Comprobar intérprete y pip

Antes de reparar, confirma qué Python y pip están activos.

python -c "import sys; print(sys.executable)"
python -m pip --version

Prefiere python -m pip al comando pip aislado. La forma de módulo utiliza el instalador asociado al intérprete elegido.

Bootstrap básico

El comando más sencillo instala pip solo cuando falta.

python -m ensurepip

La operación usa wheels incorporados y no descarga la versión más reciente. La versión disponible depende de la release de mantenimiento de CPython instalada.

Actualizar hasta la versión incorporada

Usa --upgrade para asegurar que el pip instalado sea al menos tan reciente como la copia incluida.

python -m ensurepip --upgrade

Esto no equivale a python -m pip install --upgrade pip, que normalmente consulta un índice remoto. Ensurepip continúa siendo offline.

Ejecutar dentro de un entorno virtual

Con un venv activo, ensurepip instala dentro de ese entorno.

python -m venv .venv
# Linux o macOS
source .venv/bin/activate
# Windows PowerShell:
# .venv\Scripts\Activate.ps1

python -m ensurepip --upgrade
python -m pip --version

Es el flujo más seguro para proyectos. Evita modificar el Python del sistema.

Crear venv sin pip

venv acepta --without-pip.

python -m venv --without-pip entorno
entorno/bin/python -m ensurepip

En Windows, usa entorno\Scripts\python.exe. Este patrón sirve para pruebas de bootstrap e imágenes mínimas.

Instalación de usuario

La opción --user utiliza el esquema site-packages del usuario.

python -m ensurepip --user

No está permitida dentro de un entorno virtual activo. El directorio de scripts del usuario también puede necesitar estar en PATH. La forma python -m pip sigue siendo más predecible.

Instalar bajo otra raíz

--root DIR instala relativamente a una raíz indicada.

python -m ensurepip --root /tmp/imagen-python

Está orientado a staging, creación de imágenes y empaquetado por distribuidores. No crea un entorno virtual y puede producir rutas pensadas para una instalación posterior.

Controlar nombres de scripts

Por defecto, ensurepip crea scripts como pipX y pipX.Y, donde X.Y coincide con la versión de Python.

--default-pip añade el comando simple pip:

python -m ensurepip --default-pip

--altinstall evita pipX. Las dos opciones no pueden combinarse.

Evitar confusión entre versiones

En máquinas con varios Pythons, los scripts globales pueden apuntar a entornos distintos.

python3.12 -m ensurepip --upgrade
python3.12 -m pip --version

En Windows:

py -3.12 -m ensurepip --upgrade
py -3.12 -m pip --version

Registra sys.executable en diagnósticos.

Consultar la versión incorporada

ensurepip.version() devuelve la versión de pip disponible para bootstrap.

import ensurepip

print(ensurepip.version())

Puede ser más antigua que la última release publicada. Su finalidad es proporcionar un instalador funcional compatible con CPython.

Usar bootstrap() por código

import ensurepip

ensurepip.bootstrap(
    upgrade=True,
    default_pip=True,
    verbosity=1,
)

La función acepta root, upgrade, user, altinstall, default_pip y verbosity. Activar las dos opciones de scripts genera ValueError.

Preferir subprocesso

El bootstrap programático modifica temporalmente sys.path y os.environ. Las herramientas administrativas deberían invocar la CLI en otro proceso.

import subprocess
import sys

subprocess.run(
    [sys.executable, '-m', 'ensurepip', '--upgrade'],
    check=True,
    timeout=120,
)

Esto aísla efectos y proporciona código de salida y timeout.

Evento de auditoría

El bootstrap genera el evento ensurepip.bootstrap con la raíz seleccionada. Los audit hooks pueden observarlo o bloquearlo.

En entornos gestionados, registra quién solicitó la operación, qué intérprete se utilizó y dónde se instalaron archivos.

Ensurepip solo instala pip

El módulo instala pip y los componentes inmediatos incluidos. Después usa pip para las dependencias del proyecto.

python -m ensurepip --upgrade
python -m pip install -r requirements.txt

La guía sobre instalar bibliotecas con pip explica requirements, versiones y venv.

No depender de componentes internos

El bootstrap puede instalar módulos usados por pip, pero otras aplicaciones no deben asumir que siempre estarán disponibles. Pip puede cambiar o vendorizar dependencias.

Declara explícitamente toda biblioteca que tu aplicación importe.

Disponibilidad opcional

Ensurepip es opcional en builds de CPython y no está disponible en Android, iOS ni WASI. Algunas distribuciones Linux lo eliminan o lo ofrecen en otro paquete.

Si falta el módulo, instala el paquete oficial de pip o venv de la distribución. No copies archivos aleatorios de otro Python.

Python gestionado externamente

Los sistemas modernos pueden marcar el entorno global como gestionado externamente. Instalar o actualizar paquetes globales puede romper herramientas del sistema.

python -m venv .venv
.venv/bin/python -m pip install paquete

Para aplicaciones CLI, una herramienta aislada como pipx puede ser adecuada.

Errores de permisos

Un error de permiso suele indicar que intentas escribir en Python global. No lo resuelvas automáticamente con sudo pip.

Confirma destino, usa venv o esquema de usuario y construye entornos de servidor con una cuenta dedicada.

Entornos offline

Ensurepip funciona sin red porque sus componentes vienen con Python. Instalar otras dependencias requiere wheels locales o un índice interno.

python -m pip install \
  --no-index \
  --find-links /opt/wheels \
  -r requirements.txt

Verifica hashes y procedencia. Offline no significa automáticamente confiable.

Containers

En containers, usa ensurepip únicamente cuando la imagen base no incluye pip y el build lo necesita.

Elimina caches y herramientas de compilación innecesarias de la imagen final. Los builds multi-stage ayudan a separar etapas.

Diagnosticar pip roto

Comprueba si el módulo pip puede importarse.

python -c "import pip; print(pip.__version__)"

Si falla, prueba ensurepip en un venv nuevo. Si el nuevo entorno funciona, recrear el anterior suele ser más seguro que reparar archivos manualmente.

Recrear en lugar de reparar

Los entornos virtuales deben poder reproducirse desde archivos de dependencias.

rm -rf .venv
python -m venv .venv
.venv/bin/python -m pip install -r requirements.txt

En Windows, usa el comando de eliminación apropiado. No versiones la carpeta del venv.

Confirmar con importlib.metadata

Después del bootstrap, importlib.metadata en Python puede informar la versión instalada.

from importlib.metadata import version

print(version('pip'))

Esto consulta la distribución instalada; ensurepip.version() consulta la versión incluida para bootstrap.

Probar automatizaciones

No pruebes el bootstrap en el Python global del desarrollador. Crea un entorno temporal y ejecuta su intérprete.

import subprocess
import sys

subprocess.run(
    [sys.executable, '-m', 'venv', '--without-pip', 'tmp-venv'],
    check=True,
)
subprocess.run(
    ['tmp-venv/bin/python', '-m', 'ensurepip'],
    check=True,
)

Adapta la ruta en Windows y elimina el entorno al terminar.

Errores frecuentes

• Usar ensurepip para descargar el pip más reciente.
• Confundir pip global con pip del venv.
• Llamar bootstrap en un proceso multithread.
• Combinar --altinstall y --default-pip.
• Forzar cambios en Python del sistema.
• Suponer disponibilidad en toda plataforma.
• Depender de módulos internos de pip.

Buenas prácticas

• Usa python -m pip.
• Prefiere entornos virtuales.
• Usa subprocessos para aislamiento.
• Confirma intérprete y destino.
• Respeta políticas del distribuidor.
• Recrea venvs dañados.
• Fija y verifica dependencias posteriores.

Conclusión

ensurepip en Python ofrece una forma offline y predecible de instalar o restaurar el pip incluido con CPython. Es especialmente útil para venvs creados sin pip y recuperaciones controladas.

Evita modificar el Python del sistema y no confundas bootstrap con actualización online. Consulta la documentación oficial de ensurepip y la guía de PyPA para instalar paquetes.