Gestión de dependencias (pip, requirements.txt) - parte 1

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.

El ciclo completo de un proyecto pasa por estas piezas, que conviene visualizar antes de entrar en detalle:

flowchart LR
    A[pyproject.toml] -->|declara dependencias| B["venv / uv venv"]
    B -->|entorno aislado| C[pip install o uv sync]
    C --> D[site-packages del venv]
    D --> E[python ejecuta código]
    F[requirements.txt] -->|congela versiones| C
    C -->|pip freeze| F

El fichero pyproject.toml describe qué necesita el proyecto, el entorno virtual aísla las dependencias del sistema y requirements.txt o uv.lock fijan versiones reproducibles.

¿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:PASSWORD@servidor:puerto nombre-del-paquete

O establecer variables de entorno:

# En Windows
set HTTP_PROXY=http://usuario:PASSWORD@servidor:puerto
set HTTPS_PROXY=http://usuario:PASSWORD@servidor:puerto

# En macOS/Linux
export HTTP_PROXY=http://usuario:PASSWORD@servidor:puerto
export HTTPS_PROXY=http://usuario:PASSWORD@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==version

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.