Instalar una versión específica de un paquete de Python con pip

pip instala paquetes de Python; no instala ni cambia el intérprete de Python. Para instalar una versión concreta del paquete con el intérprete que quieres usar, ejecuta python -m pip install PACKAGE==VERSION. En Windows, py -m pip install PACKAGE==VERSION puede seleccionar un destino registrado del lanzador de Python. Usa un entorno virtual cuando la fijación corresponda a un proyecto.

Instalar una versión específica del paquete con el intérprete de Python previsto

Sustituye PACKAGE y VERSION por el nombre de una distribución y una versión disponible, por ejemplo python -m pip install requests==2.32.3. El especificador == fija una versión exacta del paquete. Es útil para obtener dependencias reproducibles, pero no sirve para instalar Python 3.12, 3.13 ni otra versión del intérprete. Instala o selecciona primero ese intérprete y después invoca su módulo pip.

Es preferible usar python -m pip en lugar de un comando pip sin calificar, porque hace explícita la relación entre el intérprete y el administrador de paquetes. Comprueba el intérprete seleccionado con python --version y python -m pip --version antes de cambiar una dependencia del proyecto.

Crear o seleccionar un entorno aislado y verificarlo

Crea un entorno con python -m venv .venv y actívalo con el comando apropiado para tu shell. Después de activarlo, python --version debe identificar el intérprete del proyecto, y python -m pip --version debe mostrar una ruta bajo .venv. Si alguno de los comandos apunta a otro lugar, detente y activa el entorno correcto en vez de fijar el paquete globalmente.

Instalar y verificar una versión exacta del paquete

La siguiente prueba sin conexión crea una pequeña rueda del paquete, instala su versión exacta en un entorno virtual nuevo y muestra los metadatos instalados. En el trabajo normal, el índice de paquetes proporciona la rueda; lo importante del comando de instalación es demo-package==1.0.0.

rm -rf /tmp/pip-pin-demo
python3 -m venv /tmp/pip-pin-demo
/tmp/pip-pin-demo/bin/python /work/build_wheel.py /tmp/pip-pin-demo/wheelhouse
/tmp/pip-pin-demo/bin/python -m pip install --no-index --find-links /tmp/pip-pin-demo/wheelhouse demo-package==1.0.0
/tmp/pip-pin-demo/bin/python -m pip show demo-package | sed -n '1,3p'

La prueba ejecuta los pasos de preparación antes de esos comandos exactos y confirma esta salida:

Looking in links: /tmp/pip-pin-demo/wheelhouse
Processing /tmp/pip-pin-demo/wheelhouse/demo_package-1.0.0-py3-none-any.whl
Installing collected packages: demo-package
Successfully installed demo-package-1.0.0
Name: demo-package
Version: 1.0.0
Summary: Local package used by the pip version-pin fixture

Para una dependencia real, verifícala con python -m pip show PACKAGE o importando el paquete en el proyecto. Normalmente pip deja intacta una versión instalada si no solicitas --upgrade; añadir --upgrade puede cambiar dependencias transitivas, así que revisa la salida del resolvedor y ejecuta después las pruebas del proyecto.

Registrar las versiones fijadas en un archivo de requisitos

Para varias dependencias, coloca un requisito por línea en requirements.txt, como requests==2.32.3 y urllib3==2.2.2, y luego instálalo con python -m pip install -r requirements.txt. Haz commit de ese archivo cuando represente un entorno de aplicación reproducible. Un archivo de bloqueo creado por tu herramienta de gestión de dependencias puede ser más completo porque registra también las dependencias transitivas resueltas.

Elegir conscientemente versiones exactas, rangos compatibles o actualizaciones

Usa una versión exacta cuando el proyecto necesite una versión del paquete que ya hayas probado. Si una biblioteca es compatible con una serie de versiones, puede ser más apropiado un rango como package>=1.0,<2.0. Pon entre comillas los especificadores que contienen < o > en shells que interpretan esos signos, por ejemplo python -m pip install 'package>=1.0,<2.0'. Los especificadores de versión siguen las reglas de empaquetado de PyPA, así que no supongas que toda etiqueta de versión aparente está disponible para cualquier plataforma o versión de Python.

Diagnosticar versiones no disponibles o incompatibles

La prueba de límite solicita demo-package==9.9.9 desde un directorio de ruedas que solo contiene la versión 1.0.0. Termina con el estado 1 porque no hay ninguna distribución coincidente.

/tmp/pip-pin-demo/bin/python -m pip install --no-index --find-links /tmp/pip-pin-demo/wheelhouse demo-package==9.9.9

Si una instalación desde un índice público falla de forma similar, comprueba primero el nombre del paquete y las versiones que lista el índice. Después revisa los metadatos Requires-Python del paquete y la versión de tu intérprete; una versión antigua puede no admitir un intérprete moderno, y una versión nueva puede no admitir uno antiguo. Los conflictos de dependencias son un problema separado del resolvedor: cambia deliberadamente las restricciones del proyecto en lugar de forzar una versión antigua no relacionada. Si realmente necesitas otro intérprete de Python, instálalo mediante el sistema operativo, una distribución de Python o un gestor de versiones, crea un entorno nuevo a partir de él y usa después el python -m pip de ese intérprete.