Entornos Virtuales de Python (venv)

Un entorno virtual es un directorio autocontenido que aloja una copia privada de un intérprete de Python y su propia carpeta site-packages. Los paquetes que instalas dentro de un entorno virtual quedan completamente aislados de tu Python de sistema y de cualquier otro entorno de tu máquina — así, dos proyectos pueden depender de versiones diferentes de la misma biblioteca sin que entren en conflicto.

Este capítulo explica por qué son importantes los entornos virtuales, cómo crearlos y activarlos con el módulo integrado venv, cómo gestionar dependencias con pip y el flujo de trabajo cotidiano que sigue la mayoría de proyectos Python.

Por qué importan los entornos virtuales

Imagina que tienes dos proyectos en la misma máquina:

• Proyecto A requiere requests==2.28.0
• Proyecto B requiere requests==2.31.0

Si instalas ambas versiones en el entorno Python global, pip simplemente sobreescribe la versión que instaló primero. Uno de los proyectos dejará de funcionar. Los entornos virtuales resuelven esto dando a cada proyecto su propio directorio site-packages aislado, de modo que ambas versiones coexisten sin interferir entre sí.

Otros beneficios prácticos:

Crear un entorno virtual

Python 3.3 y versiones posteriores incluyen venv en la biblioteca estándar — no se necesita instalación adicional.

python -m venv .venv

Esto crea un directorio .venv en tu carpeta actual. El nombre .venv es una convención habitual (el punto inicial lo oculta en sistemas tipo Unix), pero puedes usar cualquier nombre que prefieras — env, venv, o incluso un nombre específico del proyecto.

Lo que venv crea dentro de .venv:

.venv/
├── bin/           # Python interpreter + activation scripts (Linux/macOS)
│   ├── activate
│   ├── python -> python3
│   └── pip
├── include/
├── lib/
│   └── python3.x/
│       └── site-packages/   # Installed packages go here
└── pyvenv.cfg               # Records the Python version and base prefix

En Windows el diseño difiere ligeramente — bin/ se llama Scripts/ y los separadores de ruta son barras invertidas.

Elegir una versión específica de Python

Si tienes varias versiones de Python instaladas, pasa el intérprete de forma explícita:

python3.11 -m venv .venv

O en Windows:

py -3.11 -m venv .venv

El archivo pyvenv.cfg dentro del entorno registra qué intérprete se utilizó, por lo que el entorno siempre se ejecuta con esa versión.

Activar el entorno

Crear el entorno no lo usa de forma automática. Debes activarlo, lo que antepone el directorio bin/ del entorno a tu PATH para que python y pip apunten a las copias del entorno.

macOS y Linux:

source .venv/bin/activate

Windows (Símbolo del sistema):

.venv\Scripts\activate.bat

Windows (PowerShell):

.venv\Scripts\Activate.ps1

Tras la activación, el prompt de tu shell normalmente muestra el nombre del entorno entre paréntesis:

(.venv) $ python --version
Python 3.12.3
(.venv) $ which python
/your/project/.venv/bin/python

Cada comando pip install que ejecutes mientras el entorno está activo instala en .venv/lib/.../site-packages/, nunca en el Python del sistema.

Desactivar

Cuando hayas terminado de trabajar en el proyecto o quieras cambiar a un entorno diferente:

deactivate

El prompt de tu shell vuelve a la normalidad y python apunta de nuevo al intérprete del sistema.

Instalar paquetes dentro de un entorno virtual

Con el entorno activo, usa pip normalmente:

pip install requests flask

Confirma que los paquetes se instalaron en el lugar correcto:

pip show requests

La línea Location: en la salida debe apuntar a tu directorio .venv.

Comprobar qué está instalado

pip list

Un entorno recién creado suele contener solo pip y setuptools. Todo lo demás que veas es algo que tú (o un archivo de requisitos) instalaste explícitamente.

Guardar y restaurar dependencias

Exportar un archivo de requisitos

Una vez configurado tu entorno, congela las versiones exactas de los paquetes para que cualquiera pueda reproducirlo:

pip freeze > requirements.txt

Un requirements.txt típico tiene este aspecto:

certifi==2024.2.2
charset-normalizer==3.3.2
flask==3.0.3
idna==3.6
requests==2.31.0
urllib3==2.2.1

Incluye requirements.txt en el control de versiones. No incluyas el directorio .venv en sí — añádelo a .gitignore.

Restaurar desde un archivo de requisitos

En una máquina nueva o en un clon reciente:

python -m venv .venv
source .venv/bin/activate        # or the Windows equivalent
pip install -r requirements.txt

Esto recrea un entorno idéntico al que congelaste.

Flujo de trabajo estándar del proyecto

La mayoría de proyectos Python siguen esta secuencia:

# 1. Clone the repository
git clone https://github.com/example/myproject.git
cd myproject

# 2. Create a virtual environment
python -m venv .venv

# 3. Activate it
source .venv/bin/activate

# 4. Install dependencies
pip install -r requirements.txt

# 5. Work on the project ...

# 6. When you add a new package, update the requirements file
pip install newpackage
pip freeze > requirements.txt

Qué añadir a .gitignore

Nunca incluyas el directorio del entorno en el control de versiones — contiene binarios compilados, es específico de la plataforma y puede ocupar decenas de megabytes. Añade uno de estos patrones a tu .gitignore:

# Virtual environment
.venv/
venv/
env/

Incluye solo requirements.txt (o pyproject.toml + requirements.txt). Eso es todo lo que alguien necesita para reconstruir el entorno desde cero.

venv frente a otras herramientas

venv es la solución integrada y suficiente para la mayoría de los casos. También puedes encontrar estas alternativas:

Para la mayoría de principiantes y proyectos sencillos, python -m venv es la elección correcta — viene incluido con Python y no requiere instalación adicional.

Errores comunes y soluciones

"python: command not found" al crear el entorno

En algunas distribuciones Linux, Python 3 se invoca como python3, no como python:

python3 -m venv .venv

PowerShell se niega a ejecutar el script de activación

Por defecto, Windows PowerShell bloquea los scripts sin firma. Habilita la ejecución de scripts para el usuario actual:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Luego ejecuta de nuevo el script de activación.

Los paquetes están instalados pero import falla

Probablemente olvidaste activar el entorno. Ejecuta:

source .venv/bin/activate

Luego intenta el import de nuevo. Puedes confirmar qué Python está activo con which python (macOS/Linux) o where python (Windows).

El entorno hace referencia a una instalación de Python eliminada

Si actualizas Python y eliminas la versión antigua, los enlaces de venv se rompen. Simplemente vuelve a crear el entorno:

rm -rf .venv
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Tabla de referencia rápida

Capítulos relacionados

• Python pip — la guía completa para instalar, actualizar y eliminar paquetes
• Python Modules — entiende cómo funciona el sistema de importación de Python
• Python Packages — organiza tu propio código en paquetes instalables

Práctica