venv: aísla entornos y dependencias Python

Un entorno virtual crea un espacio aislado para instalar las dependencias de un proyecto sin modificar los paquetes de otros proyectos ni depender de la instalación global. Aprender a usar venv en Python evita conflictos de versiones y hace que una aplicación sea más fácil de reproducir en otro equipo.

En esta guía aprenderás a crear, activar, utilizar y eliminar entornos virtuales en Windows, macOS y Linux. También verás cómo instalar paquetes, guardar dependencias, seleccionar el intérprete en un editor y resolver problemas frecuentes. Para comprender la diferencia entre módulos, paquetes y bibliotecas, consulta la guía de bibliotecas de Python.

Por qué necesitas un entorno virtual

Imagina dos proyectos. El primero necesita una versión antigua de una biblioteca y el segundo utiliza una versión nueva con cambios incompatibles. Si ambos comparten la misma instalación global, actualizar uno puede romper el otro. Un entorno virtual mantiene su propio intérprete de referencia y su propia carpeta de paquetes.

El código de tu aplicación sigue dentro de la carpeta normal del proyecto. El entorno contiene dependencias y archivos de ejecución, no reemplaza la organización del proyecto.

Comprobar Python

python --version
python -m pip --version

En algunos sistemas el comando puede ser python3. Utiliza python -m pip para asegurarte de que pip pertenece al mismo intérprete.

Crear un entorno con venv

python -m venv .venv

La carpeta .venv es una convención común, pero puedes elegir otro nombre. La documentación oficial de venv explica las opciones disponibles y el comportamiento en cada sistema.

Activar en Windows

En PowerShell:

.\.venv\Scripts\Activate.ps1

En el Símbolo del sistema:

.venv\Scripts\activate.bat

Si PowerShell bloquea el script, revisa la política de ejecución y las normas de seguridad del equipo. No desactives protecciones de forma permanente sin entender el impacto.

Activar en macOS y Linux

source .venv/bin/activate

Después de activar, el terminal normalmente muestra el nombre del entorno. Confirma qué intérprete se está utilizando:

python -c "import sys; print(sys.executable)"

Instalar paquetes dentro del entorno

python -m pip install --upgrade pip
python -m pip install requests pytest

Comprueba la instalación:

python -m pip list

La guía de módulos y paquetes en Python explica cómo se organizan los imports y por qué un paquete debe instalarse en el intérprete correcto.

Guardar dependencias con requirements.txt

python -m pip freeze > requirements.txt

En otro equipo:

python -m venv .venv
# activar el entorno
python -m pip install -r requirements.txt

pip freeze registra todas las versiones instaladas. Para proyectos mantenidos a largo plazo, distingue entre dependencias directas y transitivas y considera herramientas de gestión más avanzadas cuando sea necesario.

La guía oficial de Python Packaging sobre pip y entornos virtuales ofrece un flujo recomendado.

Desactivar el entorno

deactivate

Desactivar no elimina nada. Solo restaura el intérprete utilizado por el terminal actual.

No subir .venv al repositorio

Un entorno contiene muchos archivos específicos del sistema y puede recrearse a partir de las dependencias. Añádelo a .gitignore:

.venv/
venv/
__pycache__/
*.pyc

Sí debes guardar archivos como requirements.txt, pyproject.toml y la documentación de instalación.

Seleccionar el intérprete en VS Code

Abre la paleta de comandos y utiliza “Python: Select Interpreter”. Selecciona el ejecutable que se encuentra dentro de .venv. Si el editor muestra imports inexistentes aunque el terminal funcione, normalmente está usando otro intérprete.

import sys

print(sys.executable)
print(sys.prefix)

Estos valores ayudan a comprobar el entorno desde el propio programa.

Estructura recomendada

mi-proyecto/
├── .venv/
├── src/
│   └── aplicacion.py
├── tests/
├── requirements.txt
├── .gitignore
└── README.md

Utiliza pathlib en Python para construir rutas dentro del proyecto sin depender de separadores específicos del sistema.

Crear el entorno en una ruta distinta

python -m venv entornos/mi-proyecto

Aunque es posible, mantener .venv dentro del proyecto suele facilitar que editores y herramientas lo detecten.

Actualizar una dependencia

python -m pip install --upgrade requests
python -m pip show requests

Antes de actualizar en un proyecto importante, ejecuta las pruebas. Una nueva versión puede contener cambios incompatibles.

Eliminar y recrear un entorno

Un entorno virtual es desechable. Desactívalo, elimina la carpeta y vuelve a crearlo:

python -m venv .venv
# activar
python -m pip install -r requirements.txt

No copies un entorno entre sistemas operativos o rutas diferentes. Recrearlo es más fiable.

Error: el paquete está instalado pero no se importa

Compara estas salidas:

python -c "import sys; print(sys.executable)"
python -m pip --version
python -m pip show nombre-paquete

Si apuntan a ubicaciones distintas, instalaste el paquete con otro intérprete. Este es uno de los problemas más comunes. La guía de errores comunes de Python incluye otras comprobaciones del entorno.

Error de activación en PowerShell

La activación modifica variables del terminal, pero no es obligatoria para usar el entorno. Puedes ejecutar directamente:

.\.venv\Scripts\python.exe programa.py
.\.venv\Scripts\python.exe -m pip install requests

Esto evita dudas sobre qué intérprete se utiliza.

Entornos y variables de configuración

Un entorno virtual aísla paquetes, pero no protege secretos. Las claves de API y contraseñas deben mantenerse fuera del código y del repositorio. No confundas .venv, que contiene dependencias, con un archivo .env, que suele almacenar variables de configuración local.

Probar la reproducibilidad

1. Elimina el entorno local.
2. Crea uno nuevo.
3. Instala desde el archivo de dependencias.
4. Ejecuta pruebas y el programa.

Si el proyecto funciona solamente en el entorno antiguo, falta documentar una dependencia o una configuración. Utiliza Pytest para comprobar que la recreación mantiene el comportamiento.

Errores frecuentes

• Instalar paquetes antes de activar o seleccionar el entorno.
• Usar pip de un intérprete distinto.
• Subir la carpeta .venv al repositorio.
• Copiar el entorno entre equipos.
• Olvidar actualizar el archivo de dependencias.
• Creer que activar el entorno cambia permanentemente el sistema.
• Guardar contraseñas dentro de la carpeta del entorno.

Conclusión

Los entornos virtuales con venv aíslan las dependencias de cada proyecto y reducen conflictos. El flujo esencial es crear, activar, instalar mediante python -m pip, registrar dependencias y excluir la carpeta del repositorio.

Comprueba siempre el intérprete utilizado por el terminal y el editor. Cuando un entorno presente problemas difíciles de explicar, recréalo a partir de archivos de configuración. Un proyecto reproducible no depende de una carpeta antigua: puede reconstruirse y probarse desde cero.