Tutorial Python: Gestión de dependencias (pip, requirements.txt)

Instalación de paquetes con pip

Python cuenta con un ecosistema de paquetes extremadamente rico que extiende sus capacidades básicas. Para gestionar estos paquetes, Python incluye una herramienta llamada pip (Python Package Installer), que permite instalar, actualizar y eliminar paquetes de manera sencilla.

¿Qué es pip?

Pip es el gestor de paquetes estándar de Python que permite instalar y administrar bibliotecas y dependencias adicionales que no vienen en la biblioteca estándar. Desde Python 3.4, pip viene preinstalado con las distribuciones oficiales de Python, lo que facilita enormemente comenzar a trabajar con paquetes externos.

Verificación de pip

Antes de comenzar a instalar paquetes, es recomendable verificar que pip está correctamente instalado y actualizado:

pip --version

Si pip está instalado, verás algo similar a:

pip 23.2.1 from /usr/local/lib/python3.13/site-packages (python 3.13)

Si por alguna razón no tienes pip instalado, puedes instalarlo ejecutando:

python -m ensurepip --upgrade

Actualización de pip

Es una buena práctica mantener pip actualizado a su última versión:

python -m pip install --upgrade pip

Instalación básica de paquetes

La forma más simple de instalar un paquete es mediante el comando pip install:

pip install nombre-del-paquete

Por ejemplo, para instalar la popular biblioteca de análisis de datos pandas:

pip install pandas

Este comando descargará e instalará la última versión estable de pandas junto con todas sus dependencias.

Instalación de versiones específicas

A veces necesitarás instalar una versión específica de un paquete, lo cual puedes hacer utilizando operadores de comparación:

# Instalar una versión exacta
pip install requests==2.31.0

# Instalar una versión mínima
pip install "requests>=2.30.0"

# Instalar versión menor a una específica
pip install "requests<3.0.0"

# Combinar condiciones
pip install "requests>=2.30.0,<3.0.0"

Instalación desde diferentes fuentes

Pip permite instalar paquetes desde diversas fuentes:

• Desde PyPI (Python Package Index, el repositorio por defecto):

pip install numpy

• Desde un archivo wheel o tarball local:

pip install ./downloads/numpy-1.26.0-cp313-cp313-manylinux_2_17_x86_64.whl

• Desde un repositorio Git:

pip install git+https://github.com/usuario/proyecto.git

• Desde un repositorio Git con una rama, tag o commit específico:

pip install git+https://github.com/usuario/proyecto.git@rama
pip install git+https://github.com/usuario/proyecto.git@v1.0.0
pip install git+https://github.com/usuario/proyecto.git@8a2e4a

Instalación en entornos virtuales

Es una buena práctica instalar paquetes en entornos virtuales para evitar conflictos entre dependencias de diferentes proyectos:

# Crear un entorno virtual
python -m venv mi_entorno

# Activar el entorno virtual (en Windows)
mi_entorno\Scripts\activate

# Activar el entorno virtual (en macOS/Linux)
source mi_entorno/bin/activate

# Instalar paquetes en el entorno virtual
pip install requests

Instalación con opciones adicionales

Pip ofrece varias opciones útiles para personalizar la instalación:

• Instalación silenciosa (sin mostrar la salida de progreso):

pip install --quiet numpy

• Instalación en modo verbose (muestra información detallada):

pip install --verbose numpy

• Instalación sin usar la caché:

pip install --no-cache-dir numpy

• Instalación sin dependencias:

pip install --no-deps nombre-del-paquete

• Instalación con opciones de compilación (útil para paquetes con extensiones C):

pip install nombre-del-paquete --global-option="build_ext" --global-option="--inplace"

Instalación de múltiples paquetes

Puedes instalar varios paquetes a la vez separándolos por espacios:

pip install numpy pandas matplotlib

Instalación de paquetes para desarrollo

Si estás desarrollando un paquete y quieres instalarlo en modo "editable" (para que los cambios en el código fuente se reflejen inmediatamente sin necesidad de reinstalar):

pip install -e .

Este comando debe ejecutarse en el directorio raíz del proyecto donde se encuentra el archivo setup.py o pyproject.toml.

Instalación con extras

Algunos paquetes ofrecen funcionalidades opcionales que puedes instalar mediante "extras":

pip install requests[security]
pip install pandas[excel,hdf5]

Instalación con proxy

Si estás detrás de un proxy, puedes configurar pip para usarlo:

pip install --proxy http://usuario:contraseña@servidor:puerto nombre-del-paquete

O establecer variables de entorno:

# En Windows
set HTTP_PROXY=http://usuario:contraseña@servidor:puerto
set HTTPS_PROXY=http://usuario:contraseña@servidor:puerto

# En macOS/Linux
export HTTP_PROXY=http://usuario:contraseña@servidor:puerto
export HTTPS_PROXY=http://usuario:contraseña@servidor:puerto

Instalación desde fuentes alternativas

Por defecto, pip instala paquetes desde PyPI, pero puedes especificar fuentes alternativas:

pip install --index-url https://mi-pypi-privado.com/simple/ nombre-del-paquete

O agregar fuentes adicionales:

pip install --extra-index-url https://mi-pypi-privado.com/simple/ nombre-del-paquete

Verificación de paquetes instalados

Para ver qué paquetes están instalados y sus versiones:

pip list

Para obtener información detallada sobre un paquete específico:

pip show nombre-del-paquete

Por ejemplo:

pip show numpy

Mostrará información como:

Name: numpy
Version: 1.26.0
Summary: Fundamental package for array computing in Python
Home-page: https://numpy.org
Author: Travis E. Oliphant et al.
Author-email: 
License: BSD-3-Clause
Location: /usr/local/lib/python3.13/site-packages
Requires: 
Required-by: matplotlib, pandas, scipy

Archivo requirements.txt

Cuando trabajamos en proyectos Python de cierta complejidad, gestionar manualmente las dependencias puede convertirse en una tarea tediosa y propensa a errores. El archivo requirements.txt es una solución estándar en el ecosistema Python para documentar y gestionar las dependencias de un proyecto de manera eficiente.

¿Qué es requirements.txt?

Un archivo requirements.txt es simplemente un archivo de texto plano que lista todas las dependencias de un proyecto Python junto con sus versiones específicas. Este archivo sigue una convención ampliamente adoptada en la comunidad Python y sirve como documentación explícita de las dependencias necesarias para que el proyecto funcione correctamente.

Estructura básica

La estructura de un requirements.txt es muy sencilla. Cada línea representa una dependencia con el siguiente formato:

nombre-paquete==versión

Por ejemplo, un archivo requirements.txt típico podría verse así:

requests==2.31.0
numpy==1.26.0
pandas==2.1.1
matplotlib==3.8.0

Especificación de versiones

Existen diferentes formas de especificar las versiones de los paquetes en el archivo requirements.txt:

• Versión exacta: Garantiza reproducibilidad pero puede limitar actualizaciones de seguridad.

requests==2.31.0

• Versión mínima: Permite actualizaciones pero mantiene una base mínima.

requests>=2.31.0

• Rango de versiones: Establece límites inferior y superior.

requests>=2.31.0,<3.0.0

• Compatible con: Permite actualizaciones de parches pero no cambios mayores (siguiendo versionado semántico).

requests~=2.31.0  # Permitirá 2.31.1, 2.31.2, etc., pero no 2.32.0

• Sin especificar versión: Instala la última versión disponible (no recomendado para entornos de producción).

requests

Creación del archivo requirements.txt

Existen dos enfoques principales para crear un archivo requirements.txt:

1. Creación manual

Puedes crear el archivo manualmente listando cada dependencia que tu proyecto necesita:

# requirements.txt
flask==2.3.3
sqlalchemy==2.0.21
python-dotenv==1.0.0

2. Generación automática

Una forma más práctica es generar el archivo automáticamente a partir de las dependencias instaladas en tu entorno actual:

pip freeze > requirements.txt

El comando pip freeze captura todas las dependencias instaladas en el entorno actual junto con sus versiones exactas. Sin embargo, ten en cuenta que este enfoque incluirá todas las dependencias del entorno, incluso aquellas que no son directamente utilizadas por tu proyecto.

Uso de requirements.txt

El principal uso de requirements.txt es instalar todas las dependencias de un proyecto de una sola vez:

pip install -r requirements.txt

Este comando lee el archivo requirements.txt e instala todos los paquetes listados con las versiones especificadas.

Buenas prácticas

Organización por entornos

Para proyectos más complejos, es común tener diferentes archivos de requisitos para diferentes entornos:

requirements/
  base.txt      # Dependencias comunes
  dev.txt       # Dependencias de desarrollo
  prod.txt      # Dependencias de producción
  test.txt      # Dependencias para pruebas

Puedes hacer referencia a otros archivos de requisitos usando la sintaxis -r:

# dev.txt
-r base.txt
pytest==7.4.2
black==23.9.1
flake8==6.1.0

Comentarios y organización

Puedes incluir comentarios y organizar las dependencias para mayor claridad:

# API y comunicación HTTP
requests==2.31.0
httpx==0.25.0

# Análisis de datos
numpy==1.26.0
pandas==2.1.1
matplotlib==3.8.0  # Para visualización

# Herramientas de desarrollo
# Estas dependencias no son necesarias en producción
pytest==7.4.2
black==23.9.1

Dependencias con extras

Puedes especificar extras para paquetes que los ofrecen:

# Con soporte para formatos específicos
pandas[excel,hdf5]==2.1.1

# Con características adicionales de seguridad
requests[security]==2.31.0

Dependencias desde repositorios Git

También puedes incluir dependencias directamente desde repositorios Git:

git+https://github.com/usuario/proyecto.git@v1.0.0
git+https://github.com/usuario/proyecto.git@8a2e4a

Herramientas alternativas

Aunque requirements.txt es el estándar de facto, existen herramientas más avanzadas para la gestión de dependencias:

• pip-tools: Genera requirements.txt a partir de un archivo de alto nivel (requirements.in) y mantiene las dependencias bloqueadas.

pip install pip-tools
pip-compile requirements.in

• Poetry: Una herramienta moderna que maneja dependencias y empaquetado usando pyproject.toml.

[tool.poetry.dependencies]
python = "^3.10"
requests = "^2.31.0"
pandas = "^2.1.1"

• Pipenv: Combina pip y virtualenv, usando un Pipfile para especificar dependencias.

[[source]]
url = "https://pypi.org/simple"
verify_ssl = true
name = "pypi"

[packages]
requests = "==2.31.0"
pandas = "==2.1.1"

[dev-packages]
pytest = "==7.4.2"

Integración con control de versiones

Es una buena práctica incluir el archivo requirements.txt en el control de versiones (como Git) para que otros desarrolladores puedan reproducir fácilmente el entorno de desarrollo:

# Clonar repositorio
git clone https://github.com/usuario/proyecto.git

# Crear y activar entorno virtual
python -m venv venv
source venv/bin/activate  # En Windows: venv\Scripts\activate

# Instalar dependencias
pip install -r requirements.txt

Actualización de dependencias

Para actualizar las dependencias manteniendo el archivo requirements.txt actualizado:

# Actualizar un paquete específico
pip install --upgrade requests
pip freeze > requirements.txt

# O usar pip-tools para actualizaciones más controladas
pip-compile --upgrade-package requests requirements.in

Verificación de seguridad

Es importante revisar periódicamente las dependencias en busca de vulnerabilidades de seguridad:

# Instalar safety
pip install safety

# Verificar dependencias
safety check -r requirements.txt

También puedes usar herramientas como pip-audit o integraciones con GitHub Dependabot para automatizar este proceso.

Resolución de conflictos

Cuando trabajas con múltiples dependencias, pueden surgir conflictos de versiones. Herramientas como pip-tools o Poetry ofrecen resolución de dependencias más robusta que el simple archivo requirements.txt.

Si encuentras conflictos al instalar desde requirements.txt, puedes intentar:

pip install --no-deps -r requirements.txt
pip check

Esto instalará los paquetes sin sus dependencias y luego verificará la compatibilidad, ayudándote a identificar conflictos específicos.

Actualización y desinstalación

Mantener las dependencias de un proyecto Python actualizadas y gestionar eficientemente los paquetes instalados es una parte fundamental del ciclo de vida del desarrollo. En esta sección, exploraremos cómo actualizar y desinstalar paquetes utilizando pip, así como las mejores prácticas para estas operaciones.

Actualización de paquetes

Cuando trabajamos con proyectos a largo plazo, es común que necesitemos actualizar nuestras dependencias para obtener correcciones de errores, mejoras de rendimiento o nuevas funcionalidades.

Actualizar un paquete específico

Para actualizar un paquete a su versión más reciente:

pip install --upgrade nombre-del-paquete

O usando la forma abreviada:

pip install -U nombre-del-paquete

Por ejemplo, para actualizar la biblioteca requests:

pip install -U requests

Este comando actualizará requests a la última versión disponible, junto con sus dependencias si es necesario.

Actualizar a una versión específica

Si necesitas actualizar a una versión concreta, puedes especificarla:

pip install -U requests==2.31.0

Actualizar múltiples paquetes

Puedes actualizar varios paquetes a la vez:

pip install -U numpy pandas matplotlib

Actualizar todos los paquetes

Aunque pip no ofrece un comando directo para actualizar todos los paquetes, puedes lograrlo combinando varios comandos:

pip list --outdated --format=freeze | grep -v '^\-e' | cut -d = -f 1 | xargs -n1 pip install -U

En Windows PowerShell:

pip list --outdated --format=freeze | ForEach-Object { $_.split('==')[0] } | ForEach-Object { pip install -U $_ }

Sin embargo, esta práctica debe usarse con precaución, especialmente en entornos de producción, ya que podría romper la compatibilidad entre paquetes.

Actualizar respetando restricciones de versión

Si tienes un archivo requirements.txt con restricciones de versión, puedes actualizar los paquetes respetando esas restricciones:

pip install -U -r requirements.txt

Verificación de paquetes desactualizados

Antes de actualizar, es útil identificar qué paquetes tienen actualizaciones disponibles:

pip list --outdated

Este comando mostrará una tabla con los paquetes desactualizados, sus versiones actuales y las versiones más recientes disponibles:

Package    Version  Latest   Type
---------- -------- -------- -----
numpy      1.24.0   1.26.0   wheel
pandas     1.5.3    2.1.1    wheel
requests   2.28.2   2.31.0   wheel

Para obtener un formato más procesable por scripts:

pip list --outdated --format=json

Desinstalación de paquetes

A medida que evolucionan los proyectos, es posible que algunas dependencias dejen de ser necesarias o deban ser reemplazadas.

Desinstalar un paquete

Para eliminar un paquete instalado:

pip uninstall nombre-del-paquete

Por ejemplo:

pip uninstall requests

Por defecto, pip solicitará confirmación antes de desinstalar. Para evitar esta confirmación:

pip uninstall -y requests

Desinstalar múltiples paquetes

Puedes desinstalar varios paquetes a la vez:

pip uninstall -y numpy pandas matplotlib

Desinstalar paquetes desde un archivo

Si tienes un archivo requirements.txt y quieres desinstalar todos los paquetes listados en él:

pip uninstall -r requirements.txt

Nuevamente, puedes agregar -y para evitar las confirmaciones:

pip uninstall -y -r requirements.txt

Desinstalar dependencias no utilizadas

Pip no elimina automáticamente las dependencias que fueron instaladas junto con un paquete. Para identificar paquetes que podrían no estar siendo utilizados, puedes usar herramientas como pip-autoremove:

pip install pip-autoremove
pip-autoremove nombre-del-paquete

Gestión de conflictos y problemas

Solución de problemas de actualización

A veces, las actualizaciones pueden generar conflictos o problemas de compatibilidad:

• Conflictos de dependencias: Cuando diferentes paquetes requieren versiones incompatibles de una misma dependencia.

# Verificar la compatibilidad de los paquetes instalados
pip check

• Problemas de compilación: Algunos paquetes con extensiones en C pueden fallar al actualizarse.

# Forzar la reinstalación ignorando la caché
pip install --no-cache-dir --force-reinstall nombre-del-paquete

• Reversión a una versión anterior: Si una actualización causa problemas, puedes volver a la versión anterior.

pip install nombre-del-paquete==versión-anterior

Limpieza de caché

Pip almacena en caché los paquetes descargados. Para liberar espacio:

pip cache purge

Para ver información sobre la caché:

pip cache info

Estrategias para entornos de producción

En entornos de producción, la actualización de dependencias debe abordarse con mayor cautela:

• Pruebas de regresión: Antes de actualizar en producción, ejecuta pruebas exhaustivas en un entorno de staging.

• Actualización gradual: Considera actualizar un subconjunto de dependencias a la vez, en lugar de todas simultáneamente.

• Control de versiones estricto: Utiliza versiones exactas en tu archivo requirements.txt para producción.

• Registro de cambios: Mantén un registro de las actualizaciones realizadas:

# Guardar el estado actual antes de actualizar
pip freeze > requirements.old.txt

# Actualizar
pip install -U nombre-del-paquete

# Guardar el nuevo estado
pip freeze > requirements.new.txt

# Ver diferencias
diff requirements.old.txt requirements.new.txt

Herramientas avanzadas para actualización y mantenimiento

Para proyectos más complejos, considera estas herramientas especializadas:

• pip-tools: Proporciona un flujo de trabajo más controlado para actualizar dependencias.

# Actualizar una dependencia específica en requirements.in
pip-compile --upgrade-package requests requirements.in

• pip-review: Ofrece una interfaz interactiva para revisar y actualizar paquetes.

pip install pip-review
pip-review --interactive

• safety: Verifica vulnerabilidades de seguridad en tus dependencias.

pip install safety
safety check

• pyup: Servicio que monitoriza automáticamente tus dependencias y crea pull requests para actualizarlas.

Actualización y desinstalación en entornos virtuales

Recuerda que las operaciones de actualización y desinstalación afectan al entorno Python activo. Siempre verifica que estás trabajando en el entorno virtual correcto:

# Verificar el entorno Python activo
which python  # En Unix/Linux/macOS
where python  # En Windows

# Activar el entorno virtual si es necesario
source venv/bin/activate  # En Unix/Linux/macOS
venv\Scripts\activate     # En Windows

Mejores prácticas

• Mantén un archivo requirements.txt actualizado: Después de actualizar o desinstalar paquetes, actualiza tu archivo requirements.txt.

pip freeze > requirements.txt

• Utiliza entornos virtuales: Realiza actualizaciones en entornos aislados para evitar afectar a otros proyectos.

• Actualiza con propósito: Actualiza paquetes por razones específicas (seguridad, nuevas funcionalidades) en lugar de hacerlo rutinariamente sin motivo.

• Prueba después de actualizar: Ejecuta las pruebas de tu proyecto después de cada actualización significativa.

• Revisa los registros de cambios: Antes de actualizar un paquete importante, revisa su registro de cambios para identificar posibles problemas de compatibilidad.

• Considera el versionado semántico: Comprende cómo funciona el versionado semántico (MAJOR.MINOR.PATCH) para tomar decisiones informadas sobre actualizaciones.