Entorno virtual en Python con venv: guía completa
Un entorno virtual de Python crea un espacio aislado para las dependencias de un proyecto. Así, una aplicación puede usar una versión de una biblioteca y otra aplicación una versión distinta sin alterar la instalación global. El módulo venv forma parte de Python y cubre la mayoría de los proyectos locales.
Comprobar Python antes de empezar
Abre una terminal dentro de la carpeta del proyecto y verifica el intérprete:
python --version
En Windows también puede funcionar py --version; en macOS o Linux, python3 --version. Usa el comando que apunte a la versión deseada. Si administras varias versiones, comprueba la ruta con where python en Windows o which python3 en sistemas Unix.
Crear el entorno con venv
Desde la raíz del proyecto ejecuta:
python -m venv .venv
El nombre .venv es una convención, no una obligación. La carpeta contiene un intérprete y scripts de activación; no copies el entorno a otro equipo ni lo subas al repositorio. Añade .venv/ al archivo .gitignore.
La opción -m garantiza que ejecutas el módulo venv del intérprete elegido. Si necesitas Python 3.12, invoca explícitamente ese ejecutable o el selector disponible en tu sistema.
Activar en Windows
En PowerShell:
..venvScriptsActivate.ps1
En Símbolo del sistema:
.venvScriptsactivate.bat
Si PowerShell bloquea scripts, revisa la política de ejecución de tu organización. No cambies controles de seguridad globales sin autorización. Puedes usar otra terminal o ejecutar directamente .venvScriptspython.exe sin activar.
Activar en macOS y Linux
En bash o zsh:
source .venv/bin/activate
El prompt suele mostrar el nombre del entorno. Confirma qué ejecutable está activo con python -c seguido de una instrucción que imprima sys.executable, o con which python.
La activación solo modifica variables de la sesión para priorizar el entorno. No es imprescindible: cualquier comando puede usar la ruta completa del intérprete virtual.
Instalar paquetes correctamente
Actualiza pip si el proyecto lo requiere e instala dependencias con el intérprete activo:
python -m pip install requests
python -m pip list
Usar python -m pip reduce el riesgo de llamar a un pip perteneciente a otro intérprete. No uses permisos de administrador para instalar dentro del entorno.
Registrar dependencias
Para un proyecto sencillo puedes generar un archivo reproducible:
python -m pip freeze > requirements.txt
En otro equipo, crea un entorno nuevo e instala:
python -m pip install -r requirements.txt
freeze captura todo lo instalado, incluidas dependencias transitivas. En proyectos mantenidos, considera separar dependencias directas y bloqueadas con una herramienta específica. Lo importante es versionar la definición, no la carpeta .venv.
Integrar el entorno con VS Code
Abre la paleta de comandos, elige Python: Select Interpreter y selecciona el ejecutable dentro de .venv. La terminal, el linter, las pruebas y los notebooks deben apuntar al mismo entorno.
Si el editor marca un paquete como ausente aunque el script funciona, casi siempre está usando otro intérprete. Comprueba la ruta mostrada por el editor y la salida de sys.executable.
Desactivar y eliminar
Ejecuta deactivate para restaurar la sesión. Para eliminar el entorno, cierra procesos que lo utilicen y borra únicamente la carpeta .venv del proyecto. El código y requirements.txt permanecen intactos; puedes recrearlo cuando quieras.
No intentes reparar un entorno copiado entre sistemas. Las rutas internas y binarios pueden ser diferentes. Recrear suele ser más seguro y rápido.
Errores comunes
Si venv no está disponible en una distribución Linux, instala el paquete correspondiente desde el gestor oficial del sistema. Si python ejecuta una versión inesperada, usa su ruta completa. Si pip instala globalmente, revisa sys.executable y ejecuta python -m pip.
Un error de compilación al instalar una dependencia no siempre pertenece a venv: el paquete puede necesitar herramientas de compilación o no ofrecer una rueda para tu versión de Python. Lee el primer error relevante y consulta la documentación del paquete.
Buenas prácticas de equipo
Usa un entorno por proyecto, documenta la versión mínima de Python, fija dependencias cuando la reproducibilidad importe y ejecuta pruebas en un entorno limpio. No guardes secretos en scripts de activación ni en requirements.txt.
Para producción, construye un artefacto reproducible y analiza dependencias vulnerables. El entorno virtual aísla paquetes de Python, pero no es un contenedor de seguridad ni separa procesos del sistema operativo.
Flujo recomendado
Crea .venv, actívalo, instala desde la definición del proyecto, ejecuta las pruebas y registra solo los archivos necesarios. Si aparece una inconsistencia, elimina y recrea el entorno antes de acumular correcciones manuales.
Este hábito hace que el proyecto sea más fácil de compartir, depurar y desplegar: cada repositorio declara sus necesidades sin convertir la instalación global de Python en un conjunto impredecible de paquetes.
Continúa aprendiendo
Amplía este tema con consumir APIs con Requests, funciones lambda en Python, Docker para ciencia de datos.
Fuentes oficiales y primarias
- Documentación oficial o primaria de docs.python.org
- Documentación oficial o primaria de packaging.python.org
Preguntas frecuentes
¿Qué es un entorno virtual de Python?
Es un directorio aislado con un intérprete y paquetes propios para un proyecto.
¿Debo subir .venv a Git?
No. Versiona la definición de dependencias y recrea el entorno en cada equipo.
¿Cómo activo venv en PowerShell?
Ejecuta ..venv\Scripts\Activate.ps1 desde la raíz del proyecto, si la política de ejecución lo permite.
¿Es obligatorio activar el entorno?
No. Puedes ejecutar directamente el intérprete dentro de .venv; activar solo facilita que la terminal lo priorice.
¿Por qué pip instala en otro Python?
Probablemente pip y python apuntan a instalaciones distintas; usa python -m pip y comprueba sys.executable.
¿venv es una medida de seguridad?
No. Aísla dependencias de Python, pero no crea una frontera de seguridad como una máquina virtual o sandbox.
Deja una respuesta