Cómo configurar un entorno virtual de Python en Windows paso a paso

Qué vas a conseguir con esta configuración

Un entorno virtual permite que cada proyecto de Python tenga sus propios paquetes y versiones, separados de los demás proyectos y de la instalación general del equipo. Así puedes actualizar una biblioteca en una aplicación sin modificar las dependencias que utiliza otra.

En esta guía vas a crear una carpeta de proyecto y un entorno llamado .venv. Aprenderás a activarlo en PowerShell y en el Símbolo del sistema, verificarás qué intérprete se está ejecutando, instalarás paquetes y guardarás sus versiones en requirements.txt. También podrás desactivar, borrar y reconstruir el entorno, además de resolver los errores habituales de PATH, permisos y políticas de ejecución.

El procedimiento completo es el siguiente:

1. Comprobar que Python y pip responden desde la terminal.
2. Crear una carpeta para el proyecto.
3. Generar el entorno con el módulo venv.
4. Activarlo en PowerShell o en cmd.exe.
5. Verificar las rutas efectivas de Python y pip.
6. Instalar las dependencias del proyecto.
7. Generar y revisar requirements.txt.
8. Comprobar que el entorno puede reconstruirse desde cero.

Qué problema resuelve un entorno virtual de Python

Imagina que mantienes dos proyectos. Uno necesita una versión determinada de una biblioteca, mientras que el segundo depende de otra versión. Si instalas todos los paquetes globalmente, una actualización destinada al primer proyecto puede alterar el funcionamiento del segundo.

El módulo venv crea un directorio con su propio ejecutable de Python y un espacio independiente para instalar paquetes. La documentación actual de venv describe el funcionamiento del módulo y los scripts de activación disponibles en cada plataforma.

Un entorno virtual no duplica Windows ni crea una máquina virtual. Tampoco impide que el código acceda a los archivos o recursos permitidos al usuario. Su función es aislar el intérprete y las dependencias de Python, no proporcionar una barrera de seguridad frente a programas maliciosos.

Sin entorno virtual	Con entorno virtual
Los proyectos pueden compartir paquetes globales.	Cada proyecto mantiene sus propias dependencias.
Actualizar una biblioteca puede afectar a varias aplicaciones.	Los cambios quedan dentro del entorno seleccionado.
Resulta difícil saber qué paquetes necesita cada proyecto.	Las dependencias pueden registrarse en requirements.txt.
Se acumulan paquetes globales que quizá ya no se utilizan.	El entorno completo se puede borrar y reconstruir.

Esta separación funciona mejor cuando el código también mantiene una estructura de proyecto comprensible. La carpeta del entorno debe estar claramente diferenciada de los archivos que forman la aplicación.

Requisitos antes de crear el entorno

Necesitas una instalación funcional de Python 3 y una terminal de Windows. Puedes utilizar PowerShell o el Símbolo del sistema, aunque el comando de activación cambia de una consola a otra.

Abre una terminal y comprueba Python:

python --version

Si el comando muestra una versión, Windows ha localizado un ejecutable con ese nombre. Comprueba también que el instalador de paquetes responde a través del mismo intérprete:

python -m pip --version

Utilizar python -m pip en lugar de ejecutar solamente pip deja explícito qué intérprete inicia el instalador. Es una precaución útil cuando existen varias instalaciones de Python en el equipo.

La guía oficial de Python Packaging Authority sobre pip y entornos virtuales reúne el flujo de creación, activación e instalación de dependencias empleado en este tutorial.

Qué hacer si Windows no reconoce python

El mensaje «python no se reconoce como un comando interno o externo» significa que esa terminal no puede localizar un ejecutable llamado python. No demuestra por sí solo que Python no esté instalado: también puede indicar que su carpeta no se encuentra en PATH.

PATH es la lista de directorios en los que Windows busca los ejecutables cuando no escribes una ruta completa. Ante este error:

1. Cierra y vuelve a abrir la terminal si acabas de instalar o modificar Python.
2. Comprueba en las aplicaciones instaladas de Windows si Python aparece en el equipo.
3. Si no está instalado, obtén el instalador desde el sitio oficial de Python.
4. Si está instalado, modifica o repara la instalación para habilitar su acceso desde la terminal, o ejecuta Python mediante su ruta completa.

No continúes hasta que puedas identificar el intérprete que utilizarás. Crear el entorno con un ejecutable distinto al previsto puede producir una configuración válida, pero incompatible con los requisitos del proyecto.

Cómo configurar un entorno virtual de Python en Windows

Sitúate en el directorio donde quieras guardar el proyecto. Los siguientes comandos crean una carpeta llamada mi-proyecto y entran en ella:

mkdir mi-proyecto
cd mi-proyecto

Ahora crea el entorno virtual:

python -m venv .venv

python -m venv ejecuta el módulo estándar venv. El último argumento es el directorio de destino. En este caso se utiliza .venv, un nombre habitual que permite reconocer fácilmente la carpeta generada.

El proceso crea, entre otros elementos, un archivo pyvenv.cfg, el directorio Scripts de Windows y el espacio donde se instalarán los paquetes. Salvo que se indique lo contrario mediante las opciones de venv, el entorno también se prepara para utilizar pip.

Una estructura mínima podría quedar así:

mi-proyecto/
├── .venv/
├── requirements.txt
└── app.py

El código de la aplicación debe estar fuera de .venv. Esta carpeta contiene archivos generados para el entorno y puede eliminarse cuando sea necesario reconstruirlo.

Cómo comprobar que el entorno se ha creado

Una creación correcta puede terminar sin mostrar un mensaje de confirmación. En PowerShell puedes listar también los elementos ocultos mediante:

Get-ChildItem -Force

En el Símbolo del sistema:

dir /a

La comprobación más directa consiste en ejecutar el intérprete recién creado:

.venv\Scripts\python.exe --version

Esta prueba no activa el entorno. Solo confirma que existe un ejecutable funcional dentro de la carpeta esperada.

Activar venv en PowerShell y en el Símbolo del sistema

La activación modifica temporalmente la sesión de la terminal para que comandos como python resuelvan primero los ejecutables del entorno. Debes utilizar el script correspondiente a la consola que tengas abierta.

Consola	Comando de activación
PowerShell	.\.venv\Scripts\Activate.ps1
Símbolo del sistema	.venv\Scripts\activate.bat

Cuando la activación se completa, normalmente aparece (.venv) al comienzo del indicador:

(.venv) PS C:\proyectos\mi-proyecto>

Ese prefijo es una ayuda visual, no una verificación definitiva. El indicador de la terminal puede personalizarse y no acredita por sí mismo qué ejecutable se utilizará.

Cómo verificar que el entorno está realmente activo

En PowerShell ejecuta:

Get-Command python
python -c "import sys; print(sys.executable)"
python -m pip --version

En el Símbolo del sistema utiliza:

where python
python -c "import sys; print(sys.executable)"
python -m pip --version

La ruta impresa por sys.executable debe terminar en una ubicación equivalente a:

mi-proyecto\.venv\Scripts\python.exe

La salida de python -m pip --version también debe contener una ruta situada dentro de .venv. Estas dos comprobaciones identifican el intérprete y la instalación de pip que utilizará la terminal.

Activar el entorno es cómodo, pero no obligatorio. Puedes ejecutar directamente .venv\Scripts\python.exe. Esta alternativa resulta útil en tareas automatizadas o cuando PowerShell no permite ejecutar el script de activación.

Instalar, consultar, actualizar y eliminar paquetes

Con el entorno activado y verificado, la forma general de instalar una dependencia es:

python -m pip install nombre-paquete

Sustituye nombre-paquete por la dependencia que requiera tu aplicación. La referencia oficial de pip install documenta la sintaxis y las opciones disponibles.

Para consultar los paquetes instalados:

python -m pip list

Para actualizar un paquete concreto:

python -m pip install --upgrade nombre-paquete

Para desinstalarlo:

python -m pip uninstall nombre-paquete

También puedes actualizar pip dentro del entorno:

python -m pip install --upgrade pip

No ejecutes una actualización automática de todas las dependencias sin revisar antes la compatibilidad del proyecto. Que exista una versión más reciente de un paquete no significa que la aplicación sea compatible con ella.

Ejemplo mínimo verificable

El siguiente bloque reúne el procedimiento para PowerShell:

mkdir mi-proyecto
cd mi-proyecto
python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -c "import sys; print(sys.executable)"
python -m pip --version
python -m pip install nombre-paquete
python -m pip list

En cmd.exe solo cambia la línea de activación:

.venv\Scripts\activate.bat

nombre-paquete es deliberadamente un marcador. Debes instalar una dependencia real del proyecto, no un paquete arbitrario solo para completar el tutorial.

Si trabajas desde un editor o un entorno de desarrollo integrado, revisa también el intérprete seleccionado por esa aplicación. Activar .venv en una terminal externa no garantiza que el editor utilice automáticamente el mismo Python. Ejecutar import sys; print(sys.executable) desde el propio proyecto permite verificarlo.

Cómo generar requirements.txt

requirements.txt contiene especificaciones de paquetes que pip puede procesar posteriormente. Con el entorno activado y las dependencias revisadas, genera el archivo mediante:

python -m pip freeze > requirements.txt

La documentación oficial de pip freeze explica que el comando muestra los paquetes instalados en formato de requisitos. Para revisar el archivo desde PowerShell:

Get-Content requirements.txt

Desde el Símbolo del sistema:

type requirements.txt

Su contenido tendrá una forma similar a esta:

paquete-a==1.2.3
paquete-b==4.5.6

Los nombres y versiones anteriores solo ilustran el formato. No representan paquetes recomendados.

pip freeze refleja el estado del entorno, incluidas las dependencias instaladas por otros paquetes. Por eso conviene revisar el resultado y generarlo desde el entorno del proyecto, no desde una instalación global con herramientas ajenas.

El archivo de requisitos debe conservarse junto al proyecto. La carpeta .venv, en cambio, es un elemento generado y normalmente no se guarda en el repositorio. En un flujo de control de versiones con Git se almacena el código y la definición de dependencias, no una copia completa del entorno local.

Cómo instalar las dependencias desde requirements.txt

Para reconstruir el entorno en otra carpeta o equipo, crea uno vacío, actívalo e instala el archivo con la opción -r:

python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -r requirements.txt

En cmd.exe, utiliza esta activación:

.venv\Scripts\activate.bat

El formato admitido en este tipo de archivo está descrito en la referencia oficial de requirements.txt.

Después de instalar, verifica las rutas y consulta el estado del entorno:

python -c "import sys; print(sys.executable)"
python -m pip --version
python -m pip list

Que pip termine sin errores solo confirma que ha podido procesar e instalar las especificaciones en ese entorno. No demuestra que toda la aplicación funcione correctamente. Para comprobarlo debes ejecutar el proyecto y, cuando existan, sus pruebas automatizadas.

Desactivar, eliminar y reconstruir el entorno

Desactivar el entorno

Cuando termines de trabajar, ejecuta:

deactivate

El prefijo (.venv) debería desaparecer. Puedes volver a consultar sys.executable para comprobar qué intérprete resuelve ahora la terminal.

Eliminar el entorno

Desactívalo y borra únicamente la carpeta .venv. En PowerShell:

Remove-Item -Recurse -Force .venv

En el Símbolo del sistema:

rmdir /s /q .venv

Antes de ejecutar un borrado recursivo, comprueba el directorio actual y el nombre de la carpeta. El código debe encontrarse fuera de .venv.

Reconstruir el entorno desde cero

Si conservas el código y requirements.txt, puedes recrearlo con:

python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -r requirements.txt

Crear un entorno nuevo es preferible a copiar .venv entre equipos o ubicaciones. El entorno se genera a partir de una instalación concreta de Python y puede contener rutas o archivos vinculados a ella.

Solucionar errores de PowerShell, permisos y PATH

PowerShell bloquea Activate.ps1

PowerShell puede indicar que no puede cargar Activate.ps1 porque la ejecución de scripts está deshabilitada. Consulta primero las políticas aplicadas:

Get-ExecutionPolicy -List

La documentación de venv señala que, cuando resulte apropiado, puede ser necesario habilitar scripts firmados remotamente para el usuario actual:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

No cambies una política de seguridad sin comprender su alcance. En equipos administrados por una empresa o un centro educativo puede existir una configuración superior que debas respetar. En ese caso, solicita ayuda al administrador o utiliza una de estas alternativas:

• Activar el entorno desde cmd.exe mediante .venv\Scripts\activate.bat.
• Ejecutar directamente .venv\Scripts\python.exe.

Por ejemplo, puedes instalar una dependencia sin activar el entorno:

.venv\Scripts\python.exe -m pip install nombre-paquete

Python sigue apuntando fuera de .venv

Comprueba el ejecutable efectivo:

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

Si la ruta no contiene .venv\Scripts\python.exe:

1. Vuelve a la carpeta raíz del proyecto.
2. Comprueba que existe .venv\Scripts.
3. Ejecuta el script correspondiente a tu consola.
4. Repite la consulta de sys.executable.

Pip instala los paquetes en otra ubicación

No des por hecho que un comando pip aislado pertenece al entorno. Comprueba:

python -m pip --version

La salida debe mostrar una ruta dentro de .venv. Si no coincide, activa de nuevo el entorno o ejecuta explícitamente:

.venv\Scripts\python.exe -m pip install nombre-paquete

No se puede escribir o crear la carpeta

Si aparece un error de acceso denegado, crea el proyecto en una ubicación donde tu usuario tenga permisos de escritura. Evita abrir toda la terminal como administrador como primera solución: la elevación puede ocultar un problema de ubicación y conceder más permisos de los necesarios.

Si el error aparece al eliminar o reconstruir .venv, cierra los intérpretes, terminales o editores que puedan estar utilizando sus archivos y vuelve a intentarlo.

El entorno utiliza una versión de Python no deseada

venv utiliza el intérprete con el que ejecutas el comando de creación. Comprueba las versiones antes y después:

python --version
python -m venv .venv
.venv\Scripts\python.exe --version

Si no corresponde a la versión requerida por el proyecto, elimina .venv y créalo de nuevo ejecutando de forma explícita la instalación de Python adecuada.

Checklist final de configuración

• python --version responde antes de crear el entorno.
• Existe el directorio .venv\Scripts.
• Se ha utilizado el script de activación correspondiente a la consola.
• sys.executable apunta a .venv\Scripts\python.exe.
• python -m pip --version muestra una ruta situada dentro de .venv.
• Las dependencias se instalan mediante el Python del entorno.
• requirements.txt se ha generado y revisado.
• El entorno puede eliminarse y reconstruirse con pip install -r requirements.txt.
• La aplicación se ejecuta o supera sus pruebas después de la reconstrucción.

Configurar un entorno virtual de Python en Windows no consiste únicamente en conseguir que aparezca (.venv) en la terminal. La comprobación decisiva es verificar las rutas de Python y pip, conservar una definición revisada de las dependencias y confirmar que el proyecto puede reconstruirse en un entorno vacío.

Preguntas frecuentes

¿Es obligatorio activar el entorno virtual?

No. La activación facilita que los comandos python y pip apunten temporalmente al entorno, pero puedes ejecutar directamente .venv\Scripts\python.exe.

¿Debo crear un entorno virtual para cada proyecto?

Es recomendable cuando los proyectos tienen dependencias propias. Así evitas que instalar o actualizar un paquete en una aplicación modifique el entorno de otra.

¿Puedo borrar la carpeta .venv?

Sí, siempre que el código esté fuera de ella y conserves la información necesaria para reinstalar las dependencias. Después puedes crear otro entorno y aplicar requirements.txt.

¿Por qué funciona python pero no pip?

Puede existir una diferencia entre los ejecutables resueltos mediante PATH. Utiliza python -m pip --version para comprobar qué instalación de pip corresponde al intérprete seleccionado.

¿requirements.txt guarda el código del proyecto?

No. Contiene especificaciones de paquetes. El código, la configuración y los demás recursos deben conservarse por separado.

¿venv protege Windows frente a un programa malicioso?

No. venv aísla dependencias de Python, pero no ofrece el aislamiento de seguridad de una máquina virtual o un sandbox.

Fuentes oficiales para comprobar la configuración

Estas referencias oficiales permiten contrastar los pasos, límites y recomendaciones técnicas descritos.

• Fuente oficial: docs.python.org