Entornos virtuales y gestión de dependencias en Python: venv, pip, uv y Poetry

Entornos virtuales y gestión de dependencias en Python: venv, pip, uv y Poetry

Un entorno virtual aísla las dependencias de cada proyecto de Python, evitando conflictos entre versiones. Es una práctica fundamental en cualquier proyecto profesional.

1. venv: entornos virtuales con la biblioteca estándar

# Crear entorno virtual
python -m venv .venv

# Activar (Linux/macOS)
source .venv/bin/activate

# Activar (Windows CMD)
.venv\Scripts\activate.bat

# Activar (Windows PowerShell)
.venv\Scripts\Activate.ps1

# Verificar que estamos en el entorno
which python          # Linux/macOS
where python          # Windows
python --version

# Desactivar
deactivate

Convención: nombra el entorno .venv (con punto) para que herramientas como VS Code lo detecten automáticamente y .gitignore lo excluya por defecto.

# .gitignore
.venv/
__pycache__/
*.pyc
dist/
build/
*.egg-info/

2. pip: instalar y gestionar paquetes

# Instalar un paquete
pip install requests

# Instalar versión específica
pip install requests==2.31.0

# Instalar con restricción de versión
pip install "requests>=2.28,<3.0"

# Actualizar un paquete
pip install --upgrade requests

# Desinstalar
pip uninstall requests

# Listar paquetes instalados
pip list
pip list --outdated   # Paquetes con actualizaciones disponibles

# Mostrar información de un paquete
pip show requests

# Buscar paquetes (PyPI)
pip search pandas    # Obsoleto; usa https://pypi.org en su lugar

3. requirements.txt: congelar dependencias

# Generar requirements.txt con versiones exactas
pip freeze > requirements.txt

# Instalar desde requirements.txt
pip install -r requirements.txt

# Separar dependencias por entorno
pip install -r requirements.txt      # Producción
pip install -r requirements-dev.txt  # Desarrollo (tests, linting, etc.)

# requirements.txt (producción)
requests==2.31.0
Pillow==10.3.0
fastapi==0.111.0
uvicorn==0.30.1

# requirements-dev.txt (desarrollo)
-r requirements.txt   # Incluye las de producción
pytest==8.2.0
pytest-cov==5.0.0
mypy==1.10.0
ruff==0.4.8

4. uv: el gestor moderno (muy rápido)

uv es un gestor de paquetes escrito en Rust, hasta 100× más rápido que pip:

# Instalar uv
pip install uv
# o
curl -LsSf https://astral.sh/uv/install.sh | sh  # Linux/macOS

# Crear entorno con uv
uv venv .venv
source .venv/bin/activate  # Activar normalmente

# Instalar paquetes (mucho más rápido que pip)
uv pip install requests fastapi pillow

# Sincronizar desde requirements.txt
uv pip sync requirements.txt

# Generar lockfile
uv pip freeze > requirements.txt

# uv también gestiona versiones de Python
uv python install 3.12
uv python list

uv como herramienta de proyecto completa (uv 0.2+)

# Crear nuevo proyecto
uv init mi-proyecto
cd mi-proyecto

# Añadir dependencia (actualiza pyproject.toml automáticamente)
uv add requests fastapi

# Añadir dependencia de desarrollo
uv add --dev pytest mypy ruff

# Instalar todas las dependencias
uv sync

# Ejecutar script en el entorno del proyecto
uv run python script.py
uv run pytest
uv run mypy src/

# Ver árbol de dependencias
uv tree

5. Poetry: gestión completa de proyectos

# Instalar Poetry
curl -sSL https://install.python-poetry.org | python3 -

# Crear nuevo proyecto
poetry new mi-paquete
cd mi-paquete

# O configurar en proyecto existente
poetry init

# Añadir dependencias
poetry add requests pillow
poetry add --group dev pytest mypy

# Instalar todas las dependencias (desde pyproject.toml + poetry.lock)
poetry install

# Ejecutar comandos en el entorno de Poetry
poetry run python script.py
poetry run pytest

# Actualizar dependencias
poetry update

# Ver entorno activo
poetry env info

# Publicar en PyPI
poetry build
poetry publish

pyproject.toml con Poetry

[tool.poetry]
name        = "mi-paquete"
version     = "0.1.0"
description = "Descripción del paquete"
authors     = ["Tu Nombre <tu@email.com>"]
readme      = "README.md"

[tool.poetry.dependencies]
python   = "^3.9"
requests = "^2.28"
Pillow   = "^10.0"

[tool.poetry.group.dev.dependencies]
pytest     = "^8.0"
pytest-cov = "^5.0"
mypy       = "^1.0"
ruff       = "^0.4"

[build-system]
requires      = ["poetry-core"]
build-backend = "poetry.core.masonry.api"

6. Comparativa de herramientas

Recomendación 2025: usa uv para todo — instalar dependencias, gestionar Python, ejecutar scripts.

7. Pinning y lockfiles: reproducibilidad

# Genera lockfile con hashes de seguridad (pip-tools)
pip install pip-tools
pip-compile requirements.in --generate-hashes -o requirements.txt
pip-sync requirements.txt

# Con uv (automático)
uv lock   # Genera uv.lock
uv sync   # Instala exactamente lo del lockfile

# requirements.in (dependencias directas, sin versiones exactas)
requests>=2.28
Pillow>=10.0
fastapi>=0.111

8. Variables de entorno para dependencias

# No instalar paquetes de desarrollo en producción
pip install -r requirements.txt   # Solo producción (sin --dev)

# Con uv
uv sync --no-dev   # Excluir dependencias de dev

# Con Poetry
poetry install --without dev

9. Buenas prácticas

• Siempre usa un entorno virtual por proyecto — nunca instales paquetes globalmente.
• Añade .venv/ a .gitignore — los entornos no se comparten, las dependencias sí.
• Commits el lockfile (poetry.lock, uv.lock) para reproducibilidad exacta.
• No commits requirements.txt generado por pip freeze sin lockfile — puede incluir dependencias transitivas innecesarias.
• Separa dev de producción: pytest, mypy, ruff no deben ir a producción.
• Actualiza regularmente: uv lock --upgrade o poetry update para parches de seguridad.

10. Configuración de herramientas en pyproject.toml

# pyproject.toml — un solo archivo para toda la configuración

[tool.pytest.ini_options]
testpaths = ["tests"]
addopts   = "--cov=src --cov-report=term-missing -v"

[tool.mypy]
strict = true
ignore_missing_imports = true

[tool.ruff]
line-length = 88
select = ["E", "F", "I", "UP"]

[tool.ruff.format]
quote-style = "double"

# Con estas configuraciones, basta con:
uv run pytest         # Tests + cobertura
uv run mypy src/      # Type checking
uv run ruff check .   # Linting
uv run ruff format .  # Formateo

Conversiones relacionadas

Los proyectos Python suelen generar documentos y reportes — estas son las conversiones que más automatizan los desarrolladores:

• Markdown a PDF — release notes y docs desde .md
• Markdown a DOCX — compartir docs editables con stakeholders
• JSON a CSV — exports rápidos desde requirements.json
• CSV a JSON — fixtures para CI/tests
• HTML a PDF — outputs de Sphinx/MkDocs
• DOCX a PDF — finalizar reportes generados