Entornos virtuales en Python: venv, activación y requirements.txt

El problema que resuelven los entornos virtuales

Instala Python, ejecuta pip install requests y el paquete aterriza en un único sitio global. Eso funciona bien para un proyecto. Al tercero, empieza a doler:

• El Proyecto A necesita django==3.2. El Proyecto B necesita django==5.0. Solo uno puede tener su versión instalada globalmente.
• Quieres probar una nueva librería pero no quieres que contamine cualquier otro proyecto en tu máquina.
• Un compañero clona tu repo y no tiene ni idea de qué versiones de qué paquetes dependías.

Un entorno virtual es el arreglo. Es una carpeta autocontenida que guarda un intérprete de Python y su propio directorio de instalación de librerías. Cuando el entorno está activado, python y pip en tu terminal apuntan dentro de esa carpeta en vez de a tu Python global. Los paquetes instalados ahí se quedan ahí.

Crear uno con venv

venv viene con Python 3 — nada que instalar. Desde dentro del directorio de tu proyecto:

python3 -m venv .venv

Eso crea una carpeta .venv/ junto a tu código. El nombre .venv es una convención casi universal; el punto inicial lo mantiene fuera de la mayoría de listados de directorio, y editores como VS Code lo detectan automáticamente.

Después de que el comando termine, la carpeta contiene una instalación completa de Python (decenas de megabytes, que es normal) y un pip propio.

Activar el entorno

La activación reescribe el PATH de tu shell para que python y pip resuelvan a los de dentro de .venv/. El comando depende de tu plataforma:

# macOS / Linux
source .venv/bin/activate

# Windows (Command Prompt)
.venv\Scripts\activate.bat

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

Tu prompt obtiene un prefijo (.venv) mientras el entorno está activo — un recordatorio visual. Cualquier pip install que ejecutes ahora afecta solo a este proyecto.

Cuando termines por el día, deactivate restaura el estado anterior:

deactivate

No necesitas desactivar antes de cerrar la terminal — salir de la shell es lo mismo.

Instalar paquetes

Con el entorno activo, instala lo que necesites:

pip install requests
pip install "pandas>=2.0"
pip install --upgrade requests

Comprueba qué está instalado con pip list. Quita algo con pip uninstall requests.

Los paquetes instalados viven bajo .venv/lib/pythonX.Y/site-packages/. Nunca edites esos a mano — pip gestiona el directorio.

Fijar dependencias con requirements.txt

Tu proyecto solo es reproducible si otros pueden instalar las mismas versiones que tú usaste. La forma más simple de capturar eso es requirements.txt:

pip freeze > requirements.txt

pip freeze imprime cada paquete instalado con su versión exacta. Haz commit del archivo a git.

Cuando un colaborador (o tu yo futuro en una nueva máquina) clone el repo:

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Tres comandos y su entorno coincide con el tuyo.

Una configuración de proyecto común

El flujo completo, de principio a fin:

# Crear la carpeta del proyecto
mkdir my_tool && cd my_tool

# Crear y activar el venv
python3 -m venv .venv
source .venv/bin/activate

# Instalar dependencias
pip install requests rich

# Guardarlas
pip freeze > requirements.txt

# Trabaja en tu código...
echo "import requests; print(requests.__version__)" > main.py
python main.py

# Cuando termines
deactivate

Añade .venv a tu .gitignore

Nunca hagas commit de la carpeta .venv/. Es específica de plataforma y reproducible desde requirements.txt:

# .gitignore
.venv/
__pycache__/
*.pyc

Hacer commit infla el repo, se rompe en otras máquinas y filtra los binarios específicos del SO que tenga tu intérprete.

¿Qué versión de Python?

Por defecto, python3 -m venv .venv usa el python3 que resuelva tu shell. Si tienes varios Pythons instalados (digamos, 3.12 y 3.13), sé explícito sobre cuál:

python3.13 -m venv .venv

Una vez que el venv existe, su intérprete queda fijo — ejecutar python dentro del venv activado usa siempre esa versión específica, aunque tu Python de sistema cambie.

Cuando las cosas van mal

Unos cuantos síntomas comunes y sus arreglos:

• pip install funciona, pero mis imports fallan. Instalaste contra el Python equivocado. Activa el venv antes de pip install y vuelve a comprobar con which python (macOS/Linux) o where python (Windows).
• "ModuleNotFoundError" después de activar. El venv se creó sin ciertas librerías, o el paquete se instaló en un venv distinto. pip list muestra qué hay realmente en el actual.
• Script de activación no encontrado en Windows. PowerShell puede bloquear scripts sin firmar. Ejecuta Set-ExecutionPolicy -Scope CurrentUser RemoteSigned una vez para permitir scripts locales.
• "No module named venv". En algunas distribuciones de Linux, venv es un paquete separado. sudo apt install python3-venv en Debian/Ubuntu.

Más allá de venv: Poetry, uv, pipenv

Una vez que estés cómodo con venv + pip + requirements.txt, te encontrarás con herramientas que envuelven las mismas ideas con mejor ergonomía:

• Poetry — gestiona venvs, dependencias y packaging con un solo pyproject.toml.
• uv — un reemplazo de pip muy rápido; también gestiona venvs.
• pipenv — una herramienta más antigua que popularizó el patrón "Pipfile + Pipfile.lock".

Todas son buenas. Ninguna es requisito para aprender. Ponte cómodo con el flujo llano de venv primero; el resto son optimizaciones.

Qué te llevas

• Cada proyecto real de Python se lleva su propio entorno virtual.
• Crea uno con python3 -m venv .venv, actívalo, luego pip install libremente.
• Fija dependencias con pip freeze > requirements.txt y haz commit de ese archivo.
• Nunca hagas commit de la carpeta .venv/ en sí.
• Cuando los imports se porten mal, comprueba qué Python está activo primero.

Siguiente: el patrón __main__

Con un proyecto configurado y los paquetes instalados, un último idiomatismo cierra este capítulo — el guardia if __name__ == "__main__". Está en casi cada archivo Python pensado para ejecutarse como script, y es el tema de la siguiente página.