Entornos virtuales en Python — `venv` y `pip` sin liarte

Si llevas pocas semanas con Python, seguro que has visto a alguien hablar de “el venv”, “activar el entorno”, “el requirements.txt” — y no terminas de pillar por qué hace falta tanta movida cuando tú lo único que querías era hacer pip install requests y tirar palante.

Spoiler: hace falta. Y es lo primero que aprendes en cualquier proyecto profesional. La buena noticia es que con cinco comandos lo tienes resuelto para siempre.

En esta entrada te enseño qué es un entorno virtual, por qué te ahorra meses de dolor, cómo crearlo y activarlo en cualquier sistema operativo, cómo gestionar dependencias con pip y requirements.txt, y los errores típicos que te explotan en la cara cuando llevas un mes y sigues sin entender qué es ese (venv) que aparece en el prompt.

Por qué necesitas entornos virtuales

Imagina dos proyectos:

• Proyecto A (de hace dos años): usa Django 3.2.
• Proyecto B (nuevo): usa Django 5.0.

Si los dos comparten el mismo Python global del sistema, solo puedes tener una versión de Django instalada a la vez. Si actualizas para B, rompes A. Si bajas para A, no funciona B. Catástrofe.

Un entorno virtual es una carpeta aislada con su propio Python y su propia copia de pip. Cada proyecto vive en el suyo. Cada uno puede tener Django 3 o Django 5 sin interferir. Cuando cambias de proyecto, activas el entorno correspondiente y todo funciona.

💡 Dicho de otra forma: un venv es como un sandbox para tu proyecto. Lo que pase dentro, no afecta al sistema. Lo que pase fuera, no afecta al venv.

Si vienes de Node.js, es lo mismo que el node_modules, pero con Python. La diferencia es que en Node se crea solo y aquí lo creas tú a mano.

Crear un entorno virtual con venv

venv viene incluido en Python 3.3+. No instalas nada extra.

Te sitúas en la carpeta de tu proyecto:

cd ~/proyectos/mi-app
python3 -m venv venv

Eso crea una carpeta llamada venv/ con todo dentro: una copia del intérprete Python, pip, y las herramientas básicas. La carpeta es opaca — no la tocas a mano, solo la usas.

⚡ Tip-friki: el segundo venv (el nombre de la carpeta) es convención. Otros lo llaman .venv (con punto, oculto), env o el nombre del proyecto. Lo importante: ponlo siempre dentro del proyecto, no fuera. Y añádelo al .gitignore.

Activar el entorno

Crear el venv no lo activa. La activación cambia tu shell para que python y pip apunten a los del venv en lugar de a los del sistema.

# Linux / Mac
source venv/bin/activate

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

# Windows (cmd)
venv\Scripts\activate.bat

Después verás algo así en tu prompt:

(venv) usuario@maquina:~/proyectos/mi-app$

Ese (venv) al inicio es la señal de que el entorno está activo. A partir de aquí:

• python ya no es el de tu sistema, es el del venv.
• pip install lo-que-sea instala dentro del venv, sin tocar el sistema.
• which python (Linux/Mac) te apunta a venv/bin/python.

Desactivar y reactivar

deactivate

Esto te saca del entorno. El prompt vuelve a la normalidad. Para volver a entrar al proyecto luego, repites el source venv/bin/activate.

💡 Importante: la activación dura solo lo que dure esa terminal. Si abres otra ventana o reinicias, tienes que activar de nuevo. No es un estado global del sistema, es un estado de la sesión.

Instalar dependencias con pip

Con el venv activo, instalar paquetes es lo de siempre:

(venv) $ pip install requests
(venv) $ pip install pandas==2.1.0
(venv) $ pip install "django>=5,<6"

pip install <paquete> instala la última versión.
pip install <paquete>==<version> fija una versión exacta.
pip install "<paquete>>=X,<Y" define un rango.

Para ver qué hay instalado:

(venv) $ pip list

Para ver de dónde sale pip (te confirma que es el del venv):

(venv) $ which pip
/Users/tu/proyectos/mi-app/venv/bin/pip

Reproducibilidad: requirements.txt

Aquí está el truco que hace que tu proyecto funcione mañana en otro ordenador, en CI o cuando vuelvas a él en 6 meses.

Cuando tengas todo lo que necesitas instalado:

(venv) $ pip freeze > requirements.txt

pip freeze lista todos los paquetes con su versión exacta. Lo redireccionas a requirements.txt y lo subes al repo (sí, este sí va a git).

Cuando otra persona (o tú en otra máquina) clone el repo:

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

Y tienen exactamente las mismas versiones que tú. Reproducibilidad gratis.

⚡ Tip-friki: pip freeze lo lista TODO, incluyendo dependencias de dependencias. Para listar solo lo que tú instalaste explícitamente, mira pipreqs o pip-tools (más profesional).

Estructura típica de un proyecto

mi-app/
├── venv/                  ← NO se sube a git
├── src/
│   └── app.py
├── requirements.txt       ← SÍ se sube a git
├── .gitignore             ← incluye venv/
└── README.md

.gitignore mínimo:

venv/
.venv/
__pycache__/
*.pyc

💡 ¿Trabajas con configuración por entorno y quieres separar dev/prod? Mira el patrón if __name__ == "__main__" para entry points: if-name-main-python.

¿venv, virtualenv, pipenv, poetry, uv…?

Hay varias herramientas que hacen cosas parecidas. Resumen rápido para que no te pierdas:

Mi recomendación si empiezas: quédate con venv + pip + requirements.txt. Es lo más estándar y entender la base te permite usar cualquier herramienta más avanzada después sin perderte.

Errores típicos al empezar

# 1. Olvidar activar el venv
$ pip install requests       # ❌ instala en el sistema
# Antes:
$ source venv/bin/activate
(venv) $ pip install requests   # ✓ instala en el venv

# 2. Crear el venv pero usar otro Python
$ python3 -m venv venv       # crea con Python 3.x
(venv) $ python --version    # te dice qué versión hay dentro
# Si necesitas Python 3.11 específico:
$ python3.11 -m venv venv

# 3. Subir venv/ a git
# ❌ La carpeta venv pesa 50-200 MB y es ESPECÍFICA del sistema operativo
# ✓ Sube SOLO requirements.txt; el otro recrea el venv

# 4. Mover la carpeta del proyecto y romper el venv
$ mv mi-app /otro/sitio/
$ source /otro/sitio/mi-app/venv/bin/activate
$ python   # ❌ rutas del shebang apuntan al sitio viejo
# ✓ Si mueves: borra venv/ y créalo de nuevo, instala desde requirements.txt

# 5. Mezclar pip global y pip del venv
$ sudo pip install requests   # ❌ NUNCA con sudo. Y NUNCA fuera del venv.
(venv) $ pip install requests # ✓

Ciclo de vida típico de un proyecto

# Crear el proyecto
$ mkdir mi-app && cd mi-app
$ python3 -m venv venv
$ source venv/bin/activate
(venv) $ pip install requests pandas
(venv) $ pip freeze > requirements.txt
(venv) $ git init
(venv) $ echo "venv/" > .gitignore

# Trabajar día a día
$ cd mi-app
$ source venv/bin/activate
(venv) $ python src/app.py
(venv) $ deactivate

# Otra persona clona
$ git clone <repo>
$ cd mi-app
$ python3 -m venv venv
$ source venv/bin/activate
(venv) $ pip install -r requirements.txt

Cinco comandos en total. Una vez los memorizas, no piensas más.

Resumen

Tu siguiente paso

Una vez tienes esto interiorizado, ya no eres alguien que “sabe Python”. Eres alguien que sabe trabajar con Python en proyectos reales. Cualquier código de un repo público lo puedes clonar, crear el venv, instalar requirements y ejecutarlo.

Si quieres aprender Python desde la base hasta proyectos reales, con setup, módulos, paquetes, deploy y todo lo demás, en El Pythonista lo enseño paso a paso.

Un abrazo,
Oscar