Entornos Virtuales: Inicio Rápido

Un entorno virtual aísla las dependencias del proyecto del Python del sistema y de otros proyectos. Crea uno antes de instalar bibliotecas; es el primer paso en cualquier base de código Python real.

Receta

# uv (recomendado)
uv venv
source .venv/bin/activate
uv pip install httpx pydantic
 
# venv de la librería estándar
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip

Cuándo usar esto:

Al iniciar cualquier aplicación o biblioteca nueva
Al reproducir CI localmente con dependencias fijadas
Para evitar la deriva de versiones de "funciona en mi máquina"
Al ejecutar herramientas (ruff, mypy) sin instalaciones globales

Ejemplo de Trabajo

# Crear proyecto con uv
mkdir demo-app && cd demo-app
uv init --app
uv add fastapi uvicorn pydantic
 
# Ejecutar usando el intérprete del proyecto (no se requiere activación manual)
uv run python -c "import fastapi; print(fastapi.__version__)"
 
# Sincronizar desde el archivo de bloqueo en una clonación nueva
uv sync

# verify_env.py - ejecutar con: uv run python verify_env.py
import sys
 
def main() -> None:
    prefix = sys.prefix
    in_venv = sys.prefix != sys.base_prefix
    print(f"prefix={prefix}")
    print(f"isolated={in_venv}")
    print(f"version={sys.version.split()[0]}")
 
if __name__ == "__main__":
    main()

Lo que esto demuestra:

uv venv / uv init crea .venv junto al proyecto
uv add registra las dependencias en pyproject.toml y el archivo de bloqueo
uv run ejecuta comandos dentro del entorno del proyecto
sys.prefix != sys.base_prefix confirma el aislamiento

Inmersión Profunda

Cómo Funciona

venv copia o enlaza el intérprete base de Python en .venv.
Shim de PATH - La activación antepone .venv/bin para que python se resuelva localmente.
site-packages - Las ruedas instaladas aterrizan en .venv/lib/python3.14/site-packages.
uv - Toolchain basado en Rust: resolvedor rápido, archivo de bloqueo, uv sync, uv run.
PEP 668 - Python del sistema en muchas distribuciones de Linux se marca como "gestionado externamente" - se requiere venv.

Comparación de Herramientas

Herramienta	Fortaleza
`uv`	Velocidad, archivo de bloqueo, flujo de trabajo del proyecto
`venv`	Librería estándar, sin instalación adicional
`pip-tools`	Compilación heredada de requirements.in
`poetry` / `pdm`	Empaquetado completo + gestión de entorno

Notas de Python

# Activación en Windows
.venv\Scripts\activate
 
# Desactivar
deactivate
 
# Qué python
which python
python -c "import sys; print(sys.executable)"

Errores Comunes

Instalar globalmente - Rompe herramientas del sistema en Linux/macOS. Solución: Usa siempre venv o uv run.
Confirmar .venv - Enorme y específico de la plataforma. Solución: Ignora .venv en Git; confirma pyproject.toml + bloqueo.
Intérprete incorrecto en IDE - Ejecuta el Python del sistema sin dependencias. Solución: Selecciona .venv/bin/python en el editor.
Shell de activación obsoleto - Ruta de venv antigua después de renombrar. Solución: deactivate y reactiva.
Mezclar pip y uv - Estado de bloqueo confuso. Solución: Elige un flujo de trabajo por repositorio (preferir uv).

Alternativas

Alternativa	Usar Cuando	No Usar Cuando
`uv` project	Nuevas aplicaciones y bibliotecas	Air-gapped sin binario uv
`docker`	Paridad de despliegue	Solo verificación de sintaxis local
`pyenv`	Múltiples versiones de Python	Una sola versión es suficiente
`conda`	Pila científica con binarios	Servicio web puro

Preguntas Frecuentes

¿Debo activar el venv?

Con uv run, no. Para comandos python/pip simples, activa o usa la ruta completa .venv/bin/python.

¿Qué va en .gitignore?

.venv/, __pycache__/, .pytest_cache/, archivos .env locales con secretos.

¿uv o pip?

uv para proyectos nuevos: instalaciones y archivos de bloqueo más rápidos. pip dentro de venv está bien para scripts pequeños.

¿Cómo recreo un venv?

Elimina .venv, ejecuta uv sync o uv venv && uv pip install -r requirements.txt.

¿Puedo nombrar la carpeta venv de otra manera?

Sí, .venv es una convención. Actualiza la ruta del intérprete del IDE en consecuencia.

¿Cómo fijo Python 3.14?

Usa pyenv, uv python pin 3.14, o matriz de CI python-version: "3.14".

¿Qué es uv sync?

Instala dependencias exactamente desde uv.lock - clones y CI reproducibles.

¿Por qué el error de entorno gestionado externamente?

PEP 668 protege el Python del sistema. Crea un venv en lugar de pip install globalmente.

¿Cómo instalo herramientas de desarrollo?

uv add --dev ruff mypy pytest - mantiene las herramientas fuera de los conjuntos de dependencias de producción cuando están configuradas.

¿Incluye venv pip?

Sí, por defecto con python -m venv. uv gestiona instalaciones compatibles con pip en sus entornos.

Relacionados

Módulos, Importaciones y Paquetes - diseño de paquetes
uv - la toolchain rápida - flujo de trabajo completo de uv
pyproject.toml explicado - metadatos de dependencias
gestión de versiones de Python - pyenv y pines

Versiones de Stack: Esta página fue escrita para Python 3.14.0 (estable 3.14, mantenimiento 3.13), FastAPI 0.115+, Django 5.2, Flask 3.1, Pydantic 2, PyTorch 2.6+, pandas 2.2+, Polars 1.x, ruff 0.9+, y uv 0.6+.

Entornos Virtuales: Inicio Rápido

Receta

# uv (recomendado)
uv venv
source .venv/bin/activate
uv pip install httpx pydantic
 
# venv de la librería estándar
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip

Cuándo usar esto:

Al iniciar cualquier aplicación o biblioteca nueva
Al reproducir CI localmente con dependencias fijadas
Para evitar la deriva de versiones de "funciona en mi máquina"
Al ejecutar herramientas (ruff, mypy) sin instalaciones globales

Ejemplo de Trabajo

# Crear proyecto con uv
mkdir demo-app && cd demo-app
uv init --app
uv add fastapi uvicorn pydantic
 
# Ejecutar usando el intérprete del proyecto (no se requiere activación manual)
uv run python -c "import fastapi; print(fastapi.__version__)"
 
# Sincronizar desde el archivo de bloqueo en una clonación nueva
uv sync

# verify_env.py - ejecutar con: uv run python verify_env.py
import sys
 
def main() -> None:
    prefix = sys.prefix
    in_venv = sys.prefix != sys.base_prefix
    print(f"prefix={prefix}")
    print(f"isolated={in_venv}")
    print(f"version={sys.version.split()[0]}")
 
if __name__ == "__main__":
    main()

Lo que esto demuestra:

uv venv / uv init crea .venv junto al proyecto
uv add registra las dependencias en pyproject.toml y el archivo de bloqueo
uv run ejecuta comandos dentro del entorno del proyecto
sys.prefix != sys.base_prefix confirma el aislamiento

Inmersión Profunda

Cómo Funciona

venv copia o enlaza el intérprete base de Python en .venv.
Shim de PATH - La activación antepone .venv/bin para que python se resuelva localmente.
site-packages - Las ruedas instaladas aterrizan en .venv/lib/python3.14/site-packages.
uv - Toolchain basado en Rust: resolvedor rápido, archivo de bloqueo, uv sync, uv run.
PEP 668 - Python del sistema en muchas distribuciones de Linux se marca como "gestionado externamente" - se requiere venv.

Comparación de Herramientas

Herramienta	Fortaleza
`uv`	Velocidad, archivo de bloqueo, flujo de trabajo del proyecto
`venv`	Librería estándar, sin instalación adicional
`pip-tools`	Compilación heredada de requirements.in
`poetry` / `pdm`	Empaquetado completo + gestión de entorno

Notas de Python

# Activación en Windows
.venv\Scripts\activate
 
# Desactivar
deactivate
 
# Qué python
which python
python -c "import sys; print(sys.executable)"

Errores Comunes

Instalar globalmente - Rompe herramientas del sistema en Linux/macOS. Solución: Usa siempre venv o uv run.
Confirmar .venv - Enorme y específico de la plataforma. Solución: Ignora .venv en Git; confirma pyproject.toml + bloqueo.
Intérprete incorrecto en IDE - Ejecuta el Python del sistema sin dependencias. Solución: Selecciona .venv/bin/python en el editor.
Shell de activación obsoleto - Ruta de venv antigua después de renombrar. Solución: deactivate y reactiva.
Mezclar pip y uv - Estado de bloqueo confuso. Solución: Elige un flujo de trabajo por repositorio (preferir uv).

Alternativas

Alternativa	Usar Cuando	No Usar Cuando
`uv` project	Nuevas aplicaciones y bibliotecas	Air-gapped sin binario uv
`docker`	Paridad de despliegue	Solo verificación de sintaxis local
`pyenv`	Múltiples versiones de Python	Una sola versión es suficiente
`conda`	Pila científica con binarios	Servicio web puro

Preguntas Frecuentes

¿Debo activar el venv?

Con uv run, no. Para comandos python/pip simples, activa o usa la ruta completa .venv/bin/python.

¿Qué va en .gitignore?

.venv/, __pycache__/, .pytest_cache/, archivos .env locales con secretos.

¿uv o pip?

uv para proyectos nuevos: instalaciones y archivos de bloqueo más rápidos. pip dentro de venv está bien para scripts pequeños.

¿Cómo recreo un venv?

Elimina .venv, ejecuta uv sync o uv venv && uv pip install -r requirements.txt.

¿Puedo nombrar la carpeta venv de otra manera?

Sí, .venv es una convención. Actualiza la ruta del intérprete del IDE en consecuencia.

¿Cómo fijo Python 3.14?

Usa pyenv, uv python pin 3.14, o matriz de CI python-version: "3.14".

¿Qué es uv sync?

Instala dependencias exactamente desde uv.lock - clones y CI reproducibles.

¿Por qué el error de entorno gestionado externamente?

PEP 668 protege el Python del sistema. Crea un venv en lugar de pip install globalmente.

¿Cómo instalo herramientas de desarrollo?

uv add --dev ruff mypy pytest - mantiene las herramientas fuera de los conjuntos de dependencias de producción cuando están configuradas.

¿Incluye venv pip?

Sí, por defecto con python -m venv. uv gestiona instalaciones compatibles con pip en sus entornos.

Relacionados

Módulos, Importaciones y Paquetes - diseño de paquetes
uv - la toolchain rápida - flujo de trabajo completo de uv
pyproject.toml explicado - metadatos de dependencias
gestión de versiones de Python - pyenv y pines

Versiones de Stack: Esta página fue escrita para Python 3.14.0 (estable 3.14, mantenimiento 3.13), FastAPI 0.115+, Django 5.2, Flask 3.1, Pydantic 2, PyTorch 2.6+, pandas 2.2+, Polars 1.x, ruff 0.9+, y uv 0.6+.

Entornos Virtuales: Inicio Rápido

Buscar en la documentación

Entornos Virtuales: Inicio Rápido