Los entornos virtuales de Python resuelven uno de los problemas más habituales en el desarrollo con este lenguaje: los conflictos de dependencias entre proyectos. Cuando el Proyecto A necesita Django 4.2 y el Proyecto B necesita Django 5.0, instalar ambos de forma global rompe uno de ellos. Los entornos virtuales crean instalaciones de Python aisladas donde cada proyecto tiene sus propios paquetes, sus propias versiones y su propio pip — completamente independientes entre sí y del Python del sistema. Esta guía lo cubre todo, desde la creación del primer entorno hasta los patrones de despliegue en producción.
Requisitos Previos
- Python 3.3 o posterior instalado (
python3 --versionpara comprobarlo) - Conocimiento básico de la línea de comandos (terminal, shell o PowerShell)
- Un editor de texto o IDE para desarrollo en Python
pipdisponible (incluido por defecto desde Python 3.4+)
Crear Entornos Virtuales con venv
venv es el módulo integrado de Python para crear entornos virtuales. Viene con Python 3.3+ y no requiere ninguna instalación adicional.
Creación Básica
# Crear un entorno virtual en el directorio .venv
python3 -m venv .venv
# En algunos sistemas puede ser necesario instalar el paquete venv primero
# Debian/Ubuntu:
sudo apt install python3-venv
# Verificar que el entorno fue creado
ls .venv/
# Salida: bin/ include/ lib/ pyvenv.cfgEl nombre de directorio .venv es una convención — puedes llamarlo como quieras, pero .venv es la elección más habitual. El punto inicial lo oculta en los listados de Unix y la mayoría de las plantillas de .gitignore ya lo excluyen.
Qué Crea venv
.venv/
├── bin/ # Scripts de activación y ejecutables (Linux/macOS)
│ ├── activate # Script de activación para Bash
│ ├── activate.csh # Activación para C-shell
│ ├── activate.fish # Activación para Fish shell
│ ├── pip # pip aislado
│ ├── pip3 # Enlace simbólico a pip
│ └── python3 # Enlace simbólico al intérprete de Python
├── include/ # Cabeceras C para compilar extensiones
├── lib/python3.x/
│ └── site-packages/ # Donde pip instala los paquetes
└── pyvenv.cfg # Configuración del entornoEn Windows la estructura es similar, pero usa Scripts/ en lugar de bin/ y extensiones .exe.
Activar el Entorno
La activación modifica el PATH de tu shell para que python y pip apunten a las copias del entorno virtual en lugar de a las del sistema.
# Linux / macOS (Bash/Zsh)
source .venv/bin/activate
# Linux (Fish shell)
source .venv/bin/activate.fish
# Windows (símbolo del sistema)
.venv\Scripts\activate.bat
# Windows (PowerShell)
.venv\Scripts\Activate.ps1Al activarse, el prompt cambia para mostrar el nombre del entorno:
(.venv) user@hostname:~/myproject$Verificar que el entorno está activo:
# Comprobar qué Python se está usando
which python3
# Salida: /home/user/myproject/.venv/bin/python3
# Comprobar qué pip se está usando
which pip
# Salida: /home/user/myproject/.venv/bin/pip
# El Python del sistema no se ha tocado
python3 -c "import sys; print(sys.prefix)"
# Salida: /home/user/myproject/.venvDesactivar el Entorno
deactivateEsto restaura el PATH a su estado anterior. El entorno virtual permanece en disco — desactivarlo no elimina nada.
Gestionar Paquetes con pip
Con el entorno virtual activo, pip instala paquetes únicamente dentro de ese entorno.
Instalar Paquetes
# Instalar un paquete específico
pip install requests
# Instalar una versión específica
pip install requests==2.31.0
# Instalar con restricción de versión
pip install "requests>=2.28,<3.0"
# Instalar varios paquetes a la vez
pip install flask sqlalchemy redis
# Actualizar un paquete
pip install --upgrade requests
# Instalar desde un repositorio Git
pip install git+https://github.com/user/repo.git@mainListar e Inspeccionar Paquetes
# Listar todos los paquetes instalados
pip list
# Ver información detallada de un paquete
pip show requests
# Comprobar paquetes desactualizados
pip list --outdated
# Ver el árbol de dependencias (instala pipdeptree primero)
pip install pipdeptree
pipdeptreeDesinstalar Paquetes
# Eliminar un paquete concreto
pip uninstall requests
# Eliminar sin pedir confirmación
pip uninstall -y requestsTrabajar con requirements.txt
requirements.txt es la forma estándar de declarar y compartir las dependencias de un proyecto Python. Lista los paquetes y sus versiones para que cualquiera pueda recrear el mismo entorno.
Generar requirements.txt
# Exportar todos los paquetes instalados con sus versiones exactas
pip freeze > requirements.txtEl resultado tiene este aspecto:
certifi==2024.2.2
charset-normalizer==3.3.2
idna==3.6
requests==2.31.0
urllib3==2.2.1Instalar desde requirements.txt
# Crear un nuevo entorno e instalar las dependencias
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txtBuenas Prácticas para requirements.txt
# Fijar versiones exactas en producción (builds reproducibles)
requests==2.31.0
flask==3.0.2
# Usar >= para desarrollo de librerías (permite actualizaciones compatibles)
requests>=2.28
# Separar las dependencias de desarrollo en un segundo archivo
# requirements-dev.txt:
-r requirements.txt
pytest==8.0.0
black==24.2.0
mypy==1.8.0# Instalar dependencias de desarrollo (incluye las de producción también)
pip install -r requirements-dev.txtCaso Real: Resolución de Conflictos de Dependencias
Te unes a un equipo que trabaja en una aplicación web. Clonas el repositorio, creas un entorno virtual y ejecutas pip install -r requirements.txt. Falla con un conflicto de versiones:
ERROR: pip's dependency resolver does not currently take into account all the packages that are installed.
Package A 2.0 requires LibX>=3.0, but you have LibX 2.5 which is incompatible.Cómo solucionarlo:
# Ver qué paquete requiere el paquete conflictivo
pip install pipdeptree
pipdeptree --reverse --packages LibX
# Opción 1: Actualizar el paquete conflictivo
pip install --upgrade LibX
# Opción 2: Buscar versiones compatibles
pip install "PackageA>=2.0" "PackageB>=1.0" --dry-run
# Regenerar requirements.txt con las versiones resueltas
pip freeze > requirements.txtComparativa de Herramientas para Entornos Python
| Característica | venv | virtualenv | conda | Poetry |
|---|---|---|---|---|
| Integrado en Python | Sí (3.3+) | No (pip install) | No (instalador aparte) | No (pip install) |
| Velocidad | Moderada | Rápida | Lenta | Moderada |
| Gestión de versiones de Python | No | No | Sí | No (usar pyenv) |
| Dependencias no Python | No | No | Sí (libs C, R, etc.) | No |
| Archivo de bloqueo | No | No | environment.yml | poetry.lock |
| Resolución de dependencias | pip (básico) | pip (básico) | conda solver | Avanzada |
| Espacio en disco por entorno | ~20 MB | ~20 MB | ~500 MB+ | ~20 MB |
| Ideal para | Proyectos Python estándar | Soporte legado Python 2 | Data science, ML, cross-language | Paquetes Python modernos con deps estrictas |
Usa venv para proyectos Python estándar — es la herramienta oficial, no requiere nada extra y funciona en cualquier lugar donde corra Python. Usa conda cuando necesites dependencias que no son Python (NumPy con BLAS, CUDA, paquetes R). Usa Poetry cuando necesites resolución estricta de dependencias y un flujo moderno para publicar paquetes.
Entornos Virtuales en CI/CD y Docker
Pipelines de CI/CD (Ejemplo con GitHub Actions)
# .github/workflows/test.yml
name: Tests
on: [push, pull_request]
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-python@v5
with:
python-version: "3.12"
- name: Install dependencies
run: |
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
pip install -r requirements-dev.txt
- name: Run tests
run: |
source .venv/bin/activate
pytestDocker (Build Multietapa)
# Etapa de construcción
FROM python:3.12-slim AS builder
WORKDIR /app
COPY requirements.txt .
RUN python -m venv /opt/venv
ENV PATH="/opt/venv/bin:$PATH"
RUN pip install --no-cache-dir -r requirements.txt
# Etapa de producción
FROM python:3.12-slim
WORKDIR /app
COPY --from=builder /opt/venv /opt/venv
ENV PATH="/opt/venv/bin:$PATH"
COPY . .
CMD ["python", "app.py"]Usar un entorno virtual dentro de Docker es debatible — el contenedor ya proporciona aislamiento. Sin embargo, los builds multietapa con venv generan imágenes más pequeñas porque las herramientas de compilación y la caché de pip se quedan en la etapa de construcción.
Casos Especiales y Advertencias
Incompatibilidad de versión de Python: Un entorno virtual está vinculado a la versión de Python con la que fue creado. Si actualizas Python de 3.11 a 3.12, los entornos existentes pueden dejar de funcionar. Recréalos después de actualizaciones mayores de Python.
Fugas con --system-site-packages: Crear un entorno con python3 -m venv --system-site-packages .venv da acceso a los paquetes instalados globalmente. Es útil para paquetes difíciles de instalar con pip (como PyGObject del sistema), pero pip freeze incluirá los paquetes del sistema y contaminará tu requirements.txt. Usa pip freeze --local para listar solo los paquetes propios del entorno.
La caché de pip llena el disco: pip guarda los paquetes descargados en ~/.cache/pip/. En servidores de build, esto crece sin límite. Usa pip install --no-cache-dir o ejecuta periódicamente pip cache purge.
La activación es específica del shell: Si usas source .venv/bin/activate en un script que se ejecuta en un subshell, la activación no persiste. En su lugar, llama al binario de Python directamente: .venv/bin/python script.py o .venv/bin/pip install package.
Política de ejecución en Windows PowerShell: Por defecto, PowerShell bloquea la ejecución de scripts, incluido el de activación. Corrígelo una vez por usuario:
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUserEntornos virtuales en unidades de red compartidas: Los entornos virtuales usan enlaces simbólicos al intérprete de Python. Algunos sistemas de archivos de red (SMB, NFS) no admiten enlaces simbólicos, lo que provoca fallos en el entorno. Crea los entornos siempre en disco local.
Solución de Problemas
”No module named venv"
# Debian/Ubuntu — instalar el módulo venv
sudo apt install python3-venv
# Algunas distribuciones incluyen Python sin venv
# Verifica que está disponible:
python3 -m venv --help"pip install” falla con errores de permisos
# Si ves "Permission denied" — probablemente olvidaste activar el entorno
source .venv/bin/activate
pip install requests
# NUNCA uses sudo pip install — modifica los paquetes del sistema
# Si necesitas paquetes a nivel de sistema, usa apt/dnf en su lugarEl entorno usa la versión incorrecta de Python
# Especifica la versión de Python al crear el entorno
python3.12 -m venv .venv
# O usa la ruta completa
/usr/bin/python3.12 -m venv .venv
# Verifica la versión dentro del entorno
source .venv/bin/activate
python --versionLos paquetes se instalan de forma global en lugar de en el entorno
# Comprueba que pip pertenece al entorno
which pip
# Debe mostrar: .venv/bin/pip
# Si muestra /usr/bin/pip — el entorno no está activado
source .venv/bin/activateResumen
python3 -m venv .venvcrea un entorno Python aislado — cada proyecto tiene sus propios paquetes sin afectar a otros proyectos ni al Python del sistema- Actívalo con
source .venv/bin/activatepara que el Python y el pip del entorno sean los predeterminados en tu sesión de shell actual pip freeze > requirements.txtcaptura las versiones exactas de las dependencias — incluye este archivo en el control de versiones para que otros puedan recrear el entorno idénticopip install -r requirements.txtdentro de un entorno limpio reproduce el conjunto de dependencias — fija siempre las versiones con==en despliegues en producción- Nunca uses
sudo pip install— modifica los paquetes del sistema y genera conflictos. Los entornos virtuales eliminan por completo la necesidad de acceso root - Recrea los entornos tras actualizar Python — están vinculados a la versión de Python con la que fueron creados y pueden romperse en cambios de versión mayor