4 - Requisitos y entornos de trabajo

Objetivo del tema

En este módulo conocerás cómo documentar dependencias con pip, sincronizar proyectos escritos en Python y aislar configuraciones mediante entornos virtuales reutilizables.

4.1 Crear y usar archivos requirements.txt

Un archivo requirements.txt enumera las bibliotecas que tu proyecto necesita para ejecutarse. Guardarlo junto al código vuelve reproducible la configuración y facilita que nuevos integrantes instalen exactamente las mismas dependencias.

# requirements.txt
fastapi==0.111.0
uvicorn[standard]>=0.29,<1.0
sqlalchemy>=1.4,<2.0

• Mantiene un inventario explícito de paquetes y versiones para evitar sorpresas tras una reinstalación.
• Puedes agrupar requisitos por secciones (producción, pruebas, docs) creando archivos adicionales como requirements-dev.txt.
• Compartir este archivo en el repositorio permite que sistemas de integración continua verifiquen dependencias de forma automática.

4.2 Guardar dependencias con pip freeze

Cuando ya instalaste paquetes en el entorno activo, captura su estado con pip freeze para generar o actualizar el listado.

pip freeze > requirements.txt

• Ejecuta el comando dentro del entorno virtual correspondiente para registrar solo las dependencias del proyecto.
• Repite el proceso cada vez que agregues o actualices paquetes para mantener sincronizado el archivo con PyPI.
• Si necesitas omitir dependencias instaladas en modo editable, ejecuta pip freeze --exclude-editable > requirements.txt o limpia el archivo antes de confirmarlo.

4.3 Instalar dependencias desde un archivo

Para reconstruir un entorno en limpio utiliza la opción -r, que lee cada línea del archivo y resuelve las dependencias según las versiones declaradas.

pip install -r requirements.txt

• Ejecuta el comando en un entorno nuevo para evitar conflictos con paquetes residuales.
• Agrega el flag --upgrade si necesitas respetar rangos pero buscar la última versión disponible dentro de ellos.
• Para instalaciones reproducibles en pipelines, combina el comando con la opción --no-cache-dir y valida el resultado mediante pruebas automatizadas.

4.4 Validar dependencias con pip check

Después de instalar o actualizar es recomendable corroborar que no existan conflictos entre paquetes ni requisitos faltantes.

pip check

• El comando analiza metadatos de cada paquete y reporta cuando una dependencia requiere otra versión diferente a la disponible.
• Incluye pip check --report errores.json para generar un informe estructurado que puedas revisar con otras herramientas.
• Integrar esta verificación en tus scripts de despliegue reduce el riesgo de fallos en producción causados por incompatibilidades.

4.5 Introducción a entornos virtuales

Los entornos virtuales permiten aislar dependencias por proyecto, evitando que diferentes aplicaciones peleen por versiones de los mismos paquetes. La herramienta venv viene incluida con Python y crea directorios independientes para cada instalación.

python -m venv .venv

Para activar el entorno virtual, el comando varía según el sistema operativo y la terminal que utilices:

Windows:

• PowerShell: Ejecuta el script de activación. Es posible que necesites cambiar la política de ejecución de scripts en tu sistema si recibes un error.

  .\.venv\Scripts\Activate.ps1

• Símbolo del sistema (cmd.exe): Utiliza el siguiente comando:

  .\.venv\Scripts\activate.bat

  

macOS y Linux:

source .venv/bin/activate

• Al activar el entorno, los comandos de pip instalan paquetes dentro de la carpeta .venv sin afectar el sistema global.
• Guarda el directorio del entorno fuera del control de versiones agregándolo a .gitignore u archivos equivalentes.
• Si necesitas características avanzadas como plantillas o compatibilidad retroactiva, explora virtualenv, que ofrece utilidades extra y funciona incluso en versiones antiguas de Python.

4.6 Desactivar un entorno virtual

Cuando termines de trabajar en tu proyecto, puedes desactivar el entorno virtual para volver a la configuración global de Python. Simplemente ejecuta el siguiente comando en tu terminal:

deactivate

Este comando funciona en todos los sistemas operativos (Windows, macOS y Linux). La terminal volverá a mostrar la ruta original, indicando que el entorno virtual ya no está activo.

4.7 Otros comandos útiles para entornos virtuales

Además de activar y desactivar, existen otros comandos de gran utilidad cuando trabajas con entornos virtuales:

• Listar paquetes instalados: Para ver qué paquetes están instalados dentro del entorno virtual activo, usa:

  pip list

  Esto te mostrará una lista de las dependencias específicas de tu proyecto, aisladas del sistema global.

• Recrear un entorno virtual: Si un entorno se corrompe o necesitas empezar de cero, simplemente elimina la carpeta del entorno (por ejemplo, .venv) y créala de nuevo:

  # En Windows (PowerShell)
  Remove-Item -Recurse -Force .\.venv
  
  # En macOS y Linux
  rm -rf .venv/
  
  # Luego, vuelve a crear el entorno
  python -m venv .venv

  Posteriormente, puedes reinstalar las dependencias usando tu archivo requirements.txt.

Resumen didáctico

Documentar dependencias con archivos requirements, actualizarlos con pip freeze, restaurarlos vía pip install -r y validarlos con pip check asegura entornos repetibles. Complementar estas prácticas con entornos virtuales mantiene cada proyecto aislado y listo para desplegarse sin sorpresas.