Python: cómo crear y usar un entorno virtual por proyecto

Un entorno virtual es un directorio asociado a una instalación de Python que mantiene un conjunto propio de paquetes. El módulo estándar venv permite crearlo y, por defecto, aísla los paquetes del entorno de los instalados en la instalación base. Así, cada proyecto puede tener dependencias independientes, en vez de compartir necesariamente una única colección de paquetes en todo el equipo. Documentación oficial de venv

Imagina dos proyectos: uno requiere una versión concreta de una biblioteca y el otro depende de una versión distinta. Instalar ambas en un mismo entorno global puede provocar incompatibilidades. Con un entorno separado para cada proyecto, cada uno puede instalar sus paquetes sin modificar el conjunto del otro. La ventaja principal es el aislamiento de dependencias, no una separación completa del sistema ni una garantía de que el proyecto se ejecute igual en cualquier ordenador.

venv está incluido en la biblioteca estándar de Python desde la versión 3.3. El entorno se construye sobre una instalación existente de Python, conocida como Python base, y usa la versión del intérprete con la que se creó. Por tanto, crear un entorno no instala por sí solo cualquier versión de Python que el proyecto necesite: primero hace falta disponer del intérprete apropiado. Documentación oficial de venv

Antes de crear el entorno, abre una terminal y comprueba que Python está disponible. Los nombres de los comandos pueden variar según el sistema y la forma de instalación. En macOS y muchas distribuciones de Linux suele probarse python3 --version; en Windows, py --version o python --version. Si un comando no se reconoce, prueba las otras opciones disponibles y comprueba qué intérprete invoca cada una. Esta guía no presupone que todos los equipos tengan un comando idéntico.

Crea o abre la carpeta del proyecto y ejecuta los comandos desde allí. Un nombre habitual para el directorio del entorno es .venv: el punto inicial hace que algunos exploradores lo muestren como oculto, pero no cambia el funcionamiento de Python. La guía de empaquetado de Python también recomienda trabajar con un entorno virtual al instalar paquetes para un proyecto. Python Packaging User Guide

Comprueba asimismo que tienes permiso para escribir en la carpeta y que el intérprete seleccionado es el que deseas usar. Si tienes varias instalaciones, el resultado de --version ayuda a detectar una selección inesperada. El entorno heredará la versión del Python con el que se crea, así que conviene resolver esta elección antes de instalar paquetes.

El módulo se ejecuta como módulo de Python: -m venv indica al intérprete que invoque venv, y .venv es el directorio que se creará. Usa el comando que corresponda a tu instalación:

• Windows: py -m venv .venv (si no está disponible el lanzador py, prueba python -m venv .venv).
• macOS o Linux: python3 -m venv .venv (si python3 no existe, comprueba si python apunta al intérprete que quieres).

La documentación describe que la creación genera el directorio de destino y archivos de configuración; dentro del entorno, los ejecutables se organizan de forma distinta según la plataforma: en Windows se encuentran en Scripts, y en sistemas tipo Unix, como macOS y Linux, en bin. Documentación oficial de venv La creación no suele imprimir una confirmación detallada; puedes comprobar el resultado buscando .venv en la carpeta del proyecto. Si el comando falla, lee el mensaje completo antes de repetirlo: podría señalar un intérprete inexistente, una carpeta sin permisos o un entorno incompleto.

Una vez creado, activa el entorno con el script adecuado para el shell que estés usando. En macOS y Linux, desde la carpeta del proyecto, ejecuta source .venv/bin/activate. En Windows, el comando cambia según la terminal: en PowerShell es .venv\Scripts\Activate.ps1 (sin el espacio inicial al copiar); en el símbolo del sistema, .venv\Scripts\activate.bat. En ambos casos, omite el espacio inicial: escribe .venv\Scripts\Activate.ps1 o .venv\Scripts\activate.bat, respectivamente.

Al activarlo, la terminal suele mostrar (.venv) al comienzo del indicador. Es una señal práctica, no la única comprobación posible. Después, puedes instalar una biblioteca, por ejemplo con python -m pip install nombre-del-paquete. Invocar pip a través del python activo ayuda a asociar la instalación con el intérprete seleccionado. La documentación de empaquetado explica el flujo de instalación con pip dentro de un entorno virtual. Python Packaging User Guide

Ejecuta el programa con python archivo.py, sustituyendo archivo.py por el nombre real. Para confirmar qué intérprete estás usando, python --version informa de la versión; también puedes consultar la ruta con python -c "import sys; print(sys.executable)". Instala y ejecuta con el mismo entorno activo: así reduces el riesgo de instalar un paquete en una instalación y ejecutar el proyecto con otra.

Para salir del entorno activo, escribe deactivate y pulsa Intro. El comando deja de usar el entorno virtual en esa terminal; no elimina los archivos de .venv ni desinstala sus paquetes. Para volver a trabajar en el proyecto, abre una terminal en su carpeta y repite el comando de activación correspondiente a Windows, macOS o Linux. Documentación oficial de venv

Si la activación falla en PowerShell con un mensaje sobre la ejecución de scripts, no cambies a ciegas la configuración de seguridad del equipo. Puedes usar otra terminal compatible, como el símbolo del sistema, y consultar la documentación de Windows sobre Python para resolver la configuración específica de tu instalación. Microsoft Learn: Python en Windows Si aparece “comando no encontrado”, confirma primero que estás en la carpeta del proyecto, que .venv existe y que escribiste la ruta correspondiente a tu plataforma.

Si pip indica que un paquete ya está instalado, pero el programa no lo encuentra, verifica sys.executable y la ruta de instalación: puede que la terminal no esté usando el entorno esperado. Si el comando de creación falla porque venv no está disponible, comprueba la instalación y los componentes de Python de tu sistema; el detalle depende de cómo se haya instalado Python. No borres una instalación global como primer recurso.

Un entorno virtual es una herramienta de aislamiento local, no un archivo de especificación del proyecto. Si otra persona necesita reconstruir el conjunto de paquetes, registra las dependencias en un archivo controlado por el proyecto. Para proyectos sencillos que utilizan pip, un flujo habitual es generar una lista con python -m pip freeze > requirements.txt y, en otro entorno, instalarla con python -m pip install -r requirements.txt. La lista refleja los paquetes instalados y sus versiones en ese momento; revisa que sea adecuada para compartir y mantener antes de tratarla como una descripción completa del proyecto.

No incluyas .venv en el repositorio: suele ser un directorio local, potencialmente grande y ligado al sistema y al intérprete de origen. Incluye, en cambio, los archivos que describen el proyecto y sus dependencias, de acuerdo con el flujo que use el equipo. Al clonar o copiar el proyecto a otro equipo, crea un entorno nuevo con el Python adecuado e instala allí las dependencias registradas.

El aislamiento de venv tiene límites deliberados. No es una máquina virtual ni un contenedor: no sustituye la instalación del intérprete, no copia necesariamente todo el sistema operativo y no elimina diferencias entre plataformas. Además, como la instalación base se mantiene fuera del entorno, un entorno virtual no reemplaza las prácticas de seguridad, actualización y gestión de versiones. Para el uso cotidiano, el ciclo es sencillo: situarse en el proyecto, crear .venv, activarlo, instalar las dependencias, ejecutar el programa y desactivarlo al terminar.