Instalas un paquete para un proyecto y, de repente, otro proyecto deja de funcionar. Es el clásico conflicto de dependencias, y por eso todo desarrollador necesita un entorno virtual de Python.

Un entorno virtual da a cada proyecto su propio conjunto aislado de paquetes, de modo que las versiones nunca chocan. Se configura en unos 30 segundos y ahorra horas de depuración. En este tutorial crearás y activarás uno con venv, instalarás paquetes con pip, guardarás las dependencias, probarás uv y corregirás errores comunes.

¿Qué es un entorno virtual de Python?

Sin uno, pip install instala los paquetes en tu Python global. Puede que el proyecto A necesite requests 2.28 mientras que el B necesita una versión más reciente, y solo una puede ganar. Un entorno virtual es una carpeta con su propio enlace al intérprete y su propio site-packages, así que cada proyecto conserva las versiones que necesita.

Los proyectos de automatización de pruebas fijan las versiones de Selenium, Playwright o pytest para que los resultados sean repetibles en cualquier portátil y servidor de CI. Un entorno virtual más un archivo de requisitos es la base de eso. ¿Eres nuevo en el lenguaje? Empieza con nuestro tutorial de Python para principiantes.

Crear un entorno virtual de Python con venv

Paso 1: comprueba tu versión de Python

python --version

En algunos sistemas el comando es python3. El módulo venv viene con las versiones modernas de Python, así que no hace falta instalar nada más. Consulta la documentación oficial de venv.

Paso 2: crea el entorno

cd mi-proyecto
python -m venv .venv

Esto crea una carpeta .venv en tu proyecto. El nombre es una convención que muchas herramientas y editores detectan automáticamente.

Paso 3: actívalo

Cuando está activo, tu prompt muestra (.venv). Escribe deactivate para salir. Si PowerShell bloquea el script, permite los scripts locales para tu usuario con Set-ExecutionPolicy -Scope CurrentUser RemoteSigned.

Instalar paquetes en tu entorno virtual de Python con pip

pip install requests
pip list
pip install --upgrade requests

Comprueba que usas el pip del entorno con pip --version; la ruta debe apuntar dentro de .venv. La guía de usuario de pip explica más opciones.

Guardar y restaurar dependencias

pip freeze > requirements.txt
# más tarde, en otra máquina
python -m venv .venv
pip install -r requirements.txt

Sube requirements.txt al repositorio para que tu equipo y el CI puedan reconstruir el mismo entorno. ¿No tienes claros los commits? Lee nuestro tutorial de Git para principiantes. Añade .venv/ a tu .gitignore, porque los entornos son grandes, dependen de la máquina y se recrean fácilmente.

Prueba uv: una alternativa más rápida

uv es un gestor rápido de paquetes y proyectos de Python escrito en Rust. Crea entornos e instala paquetes mucho más rápido que pip y funciona con los mismos archivos requirements.txt.

uv venv
uv pip install requests
uv pip freeze > requirements.txt

Usar un entorno virtual de Python en proyectos reales

• VS Code: pulsa Ctrl+Shift+P, elige “Python: Select Interpreter” y selecciona el intérprete de .venv.
• Pipelines de CI: crea un entorno nuevo, instala desde el archivo de requisitos y ejecuta las pruebas, como en nuestra guía de GitHub Actions CI/CD.
• Contenedores: la misma idea se aplica en las imágenes; consulta nuestro tutorial de Docker para principiantes.
• Scripts de API y pruebas: un pequeño proyecto con requests en su propio entorno combina bien con las pruebas de API con Postman.

Errores comunes y soluciones

Buenas prácticas: un entorno por proyecto, llámalo .venv en la raíz del proyecto, fija las dependencias, ignora la carpeta en Git, recrea en lugar de reparar y documenta los pasos de instalación en el README.

Reflexiones finales

Un entorno virtual de Python es el hábito más sencillo para que los proyectos sean reproducibles. Crea uno con python -m venv .venv, actívalo, instala lo que necesites y congela tus dependencias. Cuando te resulte natural, experimenta con uv para ganar velocidad y pon tu entorno a trabajar en un pequeño script de automatización o un proyecto de pruebas.

Preguntas frecuentes

Sigue aprendiendo