Cómo instalar bibliotecas de Python con pip

Las bibliotecas permiten añadir funciones a un proyecto sin implementar todo desde cero. Con pip puedes instalar paquetes para desarrollo web, automatización, ciencia de datos, pruebas y muchas otras áreas. Aunque el comando básico es sencillo, una instalación confiable requiere comprobar el intérprete, usar entornos virtuales, fijar versiones y entender cómo resolver errores.

Antes de instalar dependencias, revisa cómo crear entornos virtuales con venv, qué son las bibliotecas de Python, cómo construir un paquete instalable y cómo instalar paquetes sin Internet.

Qué es pip

Pip es el instalador de paquetes utilizado habitualmente en Python. Consulta índices como PyPI, descarga una distribución compatible y la instala en el entorno seleccionado. Un paquete puede incluir código Python puro, archivos de datos o componentes compilados. La guía oficial de pip describe sus comandos, configuración y comportamiento.

Comprobar Python y pip

python --version
python -m pip --version

En Windows también puedes usar:

py --version
py -m pip --version

Prefiere python -m pip en lugar de ejecutar solamente pip. De este modo, pip queda vinculado al mismo intérprete que utilizas para ejecutar el proyecto.

Crear un entorno virtual

python -m venv .venv

Activa en Windows:

.venv\Scripts\activate

Activa en macOS o Linux:

source .venv/bin/activate

Después comprueba:

python -m pip --version

La ruta mostrada debe apuntar a .venv. Un entorno virtual evita mezclar dependencias de proyectos diferentes y reduce el riesgo de modificar paquetes del sistema.

Instalar una biblioteca

python -m pip install requests

Prueba la importación:

import requests
print(requests.__version__)

El nombre utilizado en pip no siempre coincide con el nombre del módulo importado. Consulta la documentación del paquete. Por ejemplo, se instala beautifulsoup4, pero se importa desde bs4.

Instalar una versión específica

python -m pip install requests==2.32.3

También puedes definir rangos:

python -m pip install "Django>=5.0,<6.0"

Las comillas evitan que el shell interprete símbolos como >. Fijar versiones exactas mejora la reproducibilidad, pero también exige actualizar conscientemente para recibir correcciones.

Actualizar un paquete

python -m pip install --upgrade requests

Antes de actualizar en producción, revisa cambios incompatibles y ejecuta pruebas. Una actualización automática sin control puede romper la aplicación.

Desinstalar y listar

python -m pip uninstall requests
python -m pip list
python -m pip show requests

pip show muestra versión, ubicación y dependencias. Esto ayuda a confirmar en qué entorno se instaló el paquete.

Guardar dependencias

python -m pip freeze > requirements.txt

Para reproducir el entorno:

python -m pip install -r requirements.txt

El archivo generado por freeze contiene todas las versiones instaladas, incluidas dependencias indirectas. Para proyectos pequeños es suficiente. En proyectos mantenidos durante años, considera separar dependencias directas y utilizar herramientas de bloqueo.

Ejemplo de requirements.txt

Flask==3.1.0
requests==2.32.3
python-dotenv==1.0.1

Añade comentarios cuando una versión tenga una razón específica:

# Se mantiene por compatibilidad con el proveedor
biblioteca==2.4.1

Instalar dependencias de desarrollo

Puedes mantener un segundo archivo:

-r requirements.txt
pytest==8.3.5
ruff==0.9.10

Guárdalo como requirements-dev.txt e instala:

python -m pip install -r requirements-dev.txt

Así los servidores de producción no necesitan herramientas de pruebas o formato.

Instalar un proyecto local

python -m pip install .

Para desarrollo editable:

python -m pip install -e .

El modo editable permite modificar el código sin reinstalar después de cada cambio. El proyecto debe definir su configuración en pyproject.toml. La guía oficial de instalación de paquetes de Python Packaging Authority explica PyPI, entornos y comandos recomendados.

Instalar desde Git

python -m pip install "git+https://github.com/usuario/[email protected]"

Fija una etiqueta o commit. Instalar directamente desde la rama principal puede producir resultados diferentes en cada momento. Revisa el código y la reputación del repositorio antes.

Instalar un archivo wheel

python -m pip install dist/mi_paquete-1.0.0-py3-none-any.whl

Las ruedas evitan compilar durante la instalación. Deben ser compatibles con el sistema, la arquitectura y la versión de Python.

Usar un índice alternativo

python -m pip install \
  --index-url https://repositorio.ejemplo/simple \
  paquete_interno

No envíes credenciales dentro de comandos guardados en el historial. Utiliza configuración segura, variables de entorno o mecanismos del sistema.

Resolver “pip no se reconoce”

Comprueba primero:

python -m pip --version

Si funciona, no necesitas añadir el ejecutable pip al PATH. Si pip no está instalado:

python -m ensurepip --upgrade

Después:

python -m pip install --upgrade pip

En Linux, la instalación de Python gestionada por la distribución puede exigir crear un entorno virtual en lugar de instalar globalmente.

Resolver ModuleNotFoundError

El error normalmente indica que instalaste el paquete en otro intérprete:

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

Compara la ruta del intérprete con la ubicación del paquete. En VS Code, selecciona el intérprete del entorno virtual.

Resolver conflictos de dependencias

python -m pip check

Este comando informa dependencias incompatibles. Crea un entorno limpio e instala desde el archivo de requisitos para verificar que el proyecto puede reconstruirse.

No soluciones todos los conflictos ejecutando actualizaciones indiscriminadas. Identifica qué paquetes exigen versiones incompatibles y revisa sus notas de versión.

Permisos y entornos administrados

Evita sudo pip install y la instalación global en sistemas donde Python es utilizado por herramientas del sistema. Crea un entorno virtual. En Windows, no es recomendable ejecutar la terminal como administrador salvo que exista una razón concreta.

Seguridad de dependencias

Comprueba el nombre exacto del paquete para evitar ataques de typosquatting. Revisa autor, proyecto, documentación, fecha de publicación y repositorio. No instales paquetes sugeridos por mensajes de error desconocidos sin verificarlos.

Fija versiones, conserva hashes cuando el entorno sea sensible y automatiza análisis de vulnerabilidades. También elimina dependencias que ya no uses para reducir la superficie de ataque.

Caché de pip

python -m pip cache dir
python -m pip cache list
python -m pip cache purge

La caché acelera instalaciones repetidas. Si sospechas que un archivo está dañado, puedes usar:

python -m pip install --no-cache-dir paquete

Configuración por usuario

Pip admite archivos de configuración para índices, timeouts y certificados. Evita guardar claves directamente en archivos que puedan compartirse. En redes corporativas, consulta al equipo de seguridad antes de desactivar verificaciones TLS.

Flujo recomendado

1. Crear un entorno virtual.
2. Actualizar pip dentro del entorno.
3. Instalar únicamente dependencias necesarias.
4. Probar importaciones y funciones principales.
5. Guardar versiones en un archivo.
6. Reconstruir el entorno desde cero.
7. Ejecutar pip check y pruebas.

Errores frecuentes

Los errores más comunes son usar pip de otro Python, instalar globalmente, olvidar activar el entorno, confundir el nombre de instalación con el nombre de importación, no fijar versiones y ejecutar comandos como administrador sin necesidad. También es frecuente incluir un archivo local con el mismo nombre que la biblioteca, por ejemplo requests.py, y bloquear la importación correcta.

Conclusión

Pip es fácil de utilizar, pero una gestión profesional de dependencias exige disciplina. Ejecuta python -m pip, trabaja dentro de entornos virtuales, fija versiones y prueba que el entorno pueda reconstruirse. Consulta fuentes oficiales, revisa la seguridad de cada paquete y evita instalaciones globales. Con este flujo, tus proyectos serán más reproducibles y fáciles de mantener.