Entornos virtuales de Python — venv y gestión de dependencias

Al finalizar este tema

Comprenderá por qué son necesarios los entornos virtuales, podrá crear entornos independientes para cada proyecto con venv y aprenderá a gestionar las dependencias mediante requirements.txt.

¿Por qué son necesarios los entornos virtuales?

Al instalar pip install requests en Python, los paquetes se instalan en el sistema global. Esto genera problemas cuando dos proyectos requieren diferentes versiones del mismo paquete.

Project A: se requiere requests==2.28.0
Project B: se requiere requests==2.31.0
Sistema: solo se puede instalar una versión de requests → ¡conflicto!

El entorno virtual crea un entorno de Python independiente para cada proyecto. Dado que cada proyecto tiene su propio conjunto de paquetes, no hay conflictos.

Project A/venv: requests==2.28.0 (independiente)
Project B/venv: requests==2.31.0 (independiente)
Python del sistema: sin impacto

Creación y activación del entorno virtual

# Crear entorno virtual
python3 -m venv venv

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

# Activar (Windows)
venv\Scripts\activate

# El indicador cambia
(venv) $ python --version
Python 3.11.5

En python3 -m venv venv, el segundo venv es el nombre de la carpeta. Por convención, se utiliza venv o .venv.

Verificación de activación

# ¿Qué Python se está utilizando?
(venv) $ which python
/home/user/project/venv/bin/python

# Desactivar
(venv) $ deactivate
$ which python
/usr/bin/python3

Al activarlo, python y pip apuntan a los del entorno virtual. Al desactivarlo, se vuelve al Python del sistema.

Instalación de paquetes dentro del entorno virtual

(venv) $ pip install requests flask

(venv) $ pip list
Package    Version
---------- -------
Flask      3.0.0
requests   2.31.0
...

Estos paquetes se instalan dentro de la carpeta venv/lib/. No afectan al Python del sistema.

requirements.txt — Registro de dependencias

# Registrar los paquetes instalados actualmente
(venv) $ pip freeze > requirements.txt

# requirements.txt
Flask==3.0.0
Jinja2==3.1.2
MarkupSafe==2.1.3
Werkzeug==3.0.1
click==8.1.7
requests==2.31.0
urllib3==2.1.0
certifi==2023.11.17
charset-normalizer==3.3.2
idna==3.6

pip freeze imprime todos los paquetes instalados junto con sus versiones exactas. Si se guarda en requirements.txt, otras personas (o servidores) podrán reproducir el mismo entorno.

Instalación de dependencias

# Instalar los mismos paquetes en otro entorno
(venv) $ pip install -r requirements.txt

Escritura manual vs. pip freeze

# Escrito manualmente (mínimo)
Flask>=3.0
requests>=2.31

# pip freeze (completo)
Flask==3.0.0
Jinja2==3.1.2
... (incluyendo todas las dependencias)

pip freeze incluye todas las dependencias, incluidas las de nivel inferior. Al escribirlo manualmente, solo se especifican los paquetes principales y el rango de versiones, lo que ofrece flexibilidad. Selecciona según el tamaño del proyecto.

.gitignore — no confirmar venv

# .gitignore
venv/
.venv/
__pycache__/
*.pyc

La carpeta del entorno virtual no se incluye en git. Razones:

1. Tamaño: La carpeta venv ocupa decenas a cientos de MB
2. Dependencia del SO: Un venv creado en macOS no funciona en Linux
3. Reproducibilidad: Con requirements.txt disponible, se puede regenerar en cualquier momento

# Iniciar el proyecto en un nuevo entorno
git clone project
cd project
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

Flujo de trabajo práctico

# 1. Iniciar el proyecto
mkdir my-project && cd my-project
python3 -m venv venv
source venv/bin/activate

# 2. Instalar paquetes
pip install flask requests pandas

# 3. Desarrollo...

# 4. Guardar dependencias
pip freeze > requirements.txt

# 5. git commit
git add .
git commit -m "Add requirements"

# 6. Otra persona lo descarga y ejecuta
git clone <repo>
cd my-project
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
python app.py

Manejo de varias versiones de Python

# Cuando Python 3.10 y 3.12 están instalados en el sistema
python3.10 -m venv venv310
python3.12 -m venv venv312

# Cada venv está vinculado a la versión de Python utilizada para crearlo
source venv310/bin/activate
python --version  # Python 3.10.x

source venv312/bin/activate
python --version  # Python 3.12.x

venv utiliza la versión de Python que estaba activa en el momento de su creación. Si se requiere una versión diferente de Python para cada proyecto, se debe crear venv con esa versión específica.

venv frente a conda

# Crear entorno conda (referencia comparativa)
conda create -n myenv python=3.11
conda activate myenv
conda install numpy pandas scikit-learn

En la ciencia de datos, conda es preferido porque paquetes como NumPy y SciPy dependen de bibliotecas en C/Fortran. Conda gestiona incluso estas dependencias binarias. Sin embargo, para el desarrollo web o proyectos Python generales, venv es suficiente.

Gestión moderna de dependencias — pyproject.toml

En proyectos con Python 3.11+, la tendencia es usar pyproject.toml en lugar de requirements.txt.

# pyproject.toml
[project]
name = "my-project"
version = "1.0.0"
requires-python = ">=3.10"
dependencies = [
    "flask>=3.0",
    "requests>=2.31",
]

[project.optional-dependencies]
dev = [
    "pytest>=7.0",
    "black>=23.0",
]

# Instalación basada en pyproject.toml
pip install .           # Dependencias de producción
pip install ".[dev]"    # Incluye dependencias de desarrollo

requirements.txt es una lista simple, mientras que pyproject.toml incluye metadatos del proyecto (nombre, versión y restricción de la versión de Python). Si planeas distribuir tu biblioteca, pyproject.toml es el estándar.

Errores frecuentes

Resumen clave

Un entorno virtual es un "Python independiente para cada proyecto". Una vez que se convierte en un hábito, desaparecen los conflictos de paquetes, el problema del "en mi computadora funciona" y las inconsistencias del entorno de distribución. Al iniciar un nuevo proyecto, ejecutar python3 -m venv venv como primer comando es la base del desarrollo en Python.