Entornos Virtuales en Python para Django 6, Flask o FastAPI con pip y uv: Guía Completa

- Andrés Cruz - EN In english

Video thumbnail

Vamos a hablar sobre los entornos virtuales en Python; específicamente nuestro caso de interés que sería para crear aplicaciones en Django 6, Flask o FastAPI —o, en resumen, cualquier proyecto en Python—. Usualmente, antes de escribir una sola línea de código, creamos un entorno virtual.

Los entornos virtuales son, sencillamente, una herramienta utilizada para crear un espacio de Python aislado del resto del Sistema Operativo, y de esta manera podemos desarrollar nuestras apps con versiones específicas de un framework, de Python o de sus dependencias.

Al desarrollar en Python, existe un problema muy común: cada proyecto requiere versiones distintas de los mismos paquetes, y aquello se vuelve un caos.

La solución que descubrí fue usar entornos virtuales, una herramienta sencilla pero poderosa que te permite mantener cada proyecto completamente aislado.

En Python, los ambientes virtuales son entornos de desarrollo aislados del sistema operativo; por lo tanto, los paquetes que instalemos no serán instalados en el sistema operativo, sino en el ambiente virtual. Podemos crear tantos ambientes virtuales como queramos —usualmente tenemos un ambiente virtual por proyecto— y con esto se manejan de manera independiente todos los paquetes y dependencias necesarios para un proyecto en Python.

Específicamente, se emplean al momento del desarrollo de software con Python; es muy común querer emplear varias versiones de un mismo paquete en diferentes proyectos, y para evitar estar instalando y desinstalando (ya que no podemos instalar dos versiones de un paquete en nuestro SO o venv), podemos crear un ambiente con el objetivo específico de aislar estas múltiples versiones de uno o varios paquetes. Por tal motivo, en este espacio se encontrarán solamente los paquetes que vas a emplear para desarrollar tus aplicaciones en Python, ya sea nativo o con algún framework como Django 6 o Flask.

En definitiva, con los entornos virtuales podemos instalar una versión específica de ese paquete que necesitamos para un proyecto o proyectos en particular, así como el resto de las dependencias que tenga un proyecto.

El Problema de las Dependencias y el Ambiente Global

Cuando instalamos Django, vas a ver que tenemos un montón de dependencias. Es decir, la instalación no solo incluye Django, sino también otros paquetes relacionados. Si ya has trabajado un poco con el ecosistema de Python, sabes a qué me refiero.

Por ejemplo, al instalar Django 6, tendremos tres o cuatro paquetes adicionales. Esto sucede porque Django, a diferencia de los micro-frameworks (como Flask), ya trae muchas cosas desarrolladas (templates, autenticación, etc.). En Flask, por ser un micro-framework que trae lo mínimo necesario, ni siquiera traía inicialmente el manejador de templates (Jinja2), y había que instalarlo como una dependencia adicional.

La idea principal es esta: instalamos Django y se instalan tres o cuatro paquetes más.

El problema es que, en el mundo real, vas a tener muchos proyectos. 

Si tuviéramos que instalar Django de manera global (como ocurre con Python, un navegador o VS Code), solo podrías tener una sola versión de Django instalada en tu sistema operativo, a menos que hagas configuraciones complejas.

Qué es un entorno virtual en Python y para qué sirve

Un entorno virtual (o virtual environment) es, básicamente, un espacio aislado dentro de tu sistema operativo donde puedes instalar paquetes de Python sin afectar al resto del sistema.
Esto significa que puedes tener varios proyectos con distintas versiones de Django o de cualquier librería sin que interfieran entre sí.

En mi caso, suelo crear un entorno nuevo para cada proyecto, especialmente cuando trabajo con frameworks como Django o Flask, porque así evito conflictos de dependencias y puedo actualizar o probar versiones sin riesgo.

En Resumen

En lugar de instalar los paquetes de manera global al sistema operativo, se crea una especie de "cajita" (un ambiente virtual) y todo lo instalamos justamente ahí.

  • Sistema Operativo Global: Si solo usamos el sistema operativo, solo podemos tener una sola instalación de una versión.
  • Ambientes Virtuales: Si empleamos ambientes virtuales, podemos tener "n" ambientes virtuales para todos nuestros proyectos.

Esto aplica a todo lo que quieras trabajar con Python (Django, FastAPI, Tkinter, Flask, etc.). Todos esos frameworks tienen dependencias que pueden chocar entre sí, y por eso no podemos instalarlas de manera global al sistema operativo. Si lo hiciéramos, tendríamos problemas (algo que veremos en una comparación cuando empecemos a instalar Django).

Ventajas de usar entornos virtuales en Django, Flask o FastAPI

  • Aíslan tus dependencias por proyecto.
  • Evitan conflictos entre versiones de paquetes.
  • Te permiten compartir fácilmente tus requerimientos con otros desarrolladores.
  • Facilitan la instalación de entornos iguales en distintos equipos.

Diferencia entre venv, virtualenv y uv

  • venv: viene integrado con Python 3, así que no necesitas instalar nada extra. Es la opción más simple para empezar.
  • virtualenv: es un paquete externo que ofrece más flexibilidad, sobre todo si usas varias versiones de Python. Fue la herramienta estándar durante años.
  • uv: es el nuevo estándar del ecosistema. Escrito en Rust, reemplaza a pip, pip-tools y virtualenv en una sola herramienta. Su velocidad de ejecución es entre 10 y 100 veces superior a las herramientas tradicionales y resuelve de forma nativa los problemas multiplataforma que pip arrastra desde hace años. Si estás empezando un proyecto hoy, te recomiendo que vayas directamente con uv.
  • Yo utilizo venv la mayoría de las veces en proyectos legados, pero para proyectos nuevos ya me he pasado completamente a uv.

Enfoque Clásico: Crear un entorno virtual con pip y venv

Este es el flujo que ha funcionado durante años y que sigue siendo perfectamente válido para proyectos sencillos o si tu equipo aún no ha migrado a uv.

Requisitos previos antes de crear tu entorno

Antes de empezar, asegúrate de tener Python y pip instalados correctamente en tu sistema.

Abre tu terminal (o CMD en Windows) y escribe:

$ python --version
$ pip --version

Si obtienes un número de versión, todo está en orden. Si no, puedes descargar Python desde python.org/downloads.

Instalar la herramienta virtualenv

Si prefieres usar virtualenv en lugar de venv, instala el paquete así:

$ pip install virtualenv

Este comando descargará e instalará la herramienta necesaria para crear entornos virtuales.

Crear un entorno virtual paso a paso

Ya con esto podemos crear los entornos virtuales. Con virtualenv:

$ virtualenv <myproject>

En donde <myproject> es el nombre de tu entorno virtual. El comando anterior crea una carpeta con ese nombre, y esa carpeta es tu entorno virtual, listo para emplear.

También puedes crear el entorno con el módulo venv que ya viene integrado en Python 3 (sin instalar nada extra):

$ python3 -m venv <myproject>

Estructura de carpetas generada

Una vez creado el entorno, verás algo como esto:

myproject/
│
├── Scripts/      (en Windows)
├── bin/          (en Linux/macOS)
├── Lib/
└── pyvenv.cfg

Activar y desactivar el entorno virtual

Dentro de la carpeta del entorno encontrarás archivos llamados activate y deactivate que te permiten activar o desactivar el entorno virtual.

Lo primero que quisiéramos hacer sería activar nuestro ambiente virtual:

En Windows:

$ myproject\Scripts\activate

Notarás que el nombre del entorno aparece al inicio de tu línea de comandos, por ejemplo:

(myproject) C:\Users\andre\Escritorio>

En Linux y macOS:

$ source myproject/bin/activate

Y si queremos desactivar el entorno virtual, simplemente ejecutamos:

$ deactivate

Recordemos qué son los ambientes virtuales

Los ambientes virtuales son, por decirlo de alguna manera, una cajita aislada del sistema operativo.
Dentro de esta cajita tenemos todos los paquetes y dependencias necesarios para un proyecto específico.

Independientemente de la jerga que usemos —ya sea en Django o en otro framework—, cada proyecto o aplicación (por ejemplo, una tienda en línea) suele estar vinculado a un único ambiente virtual.

Por qué crear un ambiente virtual por proyecto

Si deseas crear otro proyecto en Django, lo ideal es crear un nuevo ambiente virtual.
Esto se debe a que, muy probablemente, esos proyectos trabajarán con paquetes o versiones diferentes.

Por ejemplo, además de Django, solemos instalar otros complementos aprovechando el ecosistema de Python.
Cada proyecto puede requerir librerías distintas, por lo que mantener los ambientes separados garantiza que las dependencias sean exclusivas y evita mezclar configuraciones entre proyectos.

Ejercicio práctico con venv

Por ejemplo, si ejecutamos el siguiente comando:

$ python3 -m venv vtasks

Este generará el entorno virtual, que no es más que una carpeta con varios archivos y subcarpetas. Para activarlo:

En macOS o Linux:

$ source vtasks/bin/activate

En Windows:

$ vtasks\Scripts\activate

La carpeta de tu proyecto (no la de vtasks, que corresponde al ambiente virtual) es la que te recomiendo que abras en Visual Studio Code (o el editor de tu preferencia). Desde la terminal de VS Code, recuerda activar el ambiente virtual:

Terminal VSC

Instalar Django, Flask o FastAPI dentro del entorno virtual

Una vez activado el entorno, nuestra terminal luce de la siguiente manera:

venv activado en terminal o CMD

Y con esto podemos instalar el framework que necesitemos. Por ejemplo:

Django:

$ pip install django

Flask:

$ pip install flask

FastAPI:

$ pip install fastapi uvicorn

uvicorn es un servidor web HTTP de tipo ASGI (Asynchronous Server Gateway Interface) que podemos usar en múltiples frameworks web asíncronos de Python, como Django, Flask y por supuesto FastAPI. Para instalarlo junto con FastAPI, podemos usar un solo comando:

$ pip install fastapi uvicorn

Y esto es todo: ya tenemos Django (o el framework que hayas seleccionado) instalado en nuestro entorno virtual. Por ahora solo instalamos un paquete; no tenemos un proyecto todavía, pero con este paquete podemos crearlos.

Si hacemos un:

$ pip freeze

Verás todos los paquetes que componen la instalación; algo como:

asgiref==3.11.0
Django==6.0
sqlparse==0.5.4
tzdata==2025.2

Como comentamos antes, es muy común que al instalar paquetes vía pip, estos paquetes también necesiten de otros paquetes para funcionar; estos se instalan automáticamente y se les conoce como dependencias.

En el ejemplo anterior, los paquetes asgiref, sqlparse y tzdata son dependencias del paquete Django.

Es importante notar que seguramente tú tendrás versiones un poco más recientes y no exactamente las mismas listadas aquí (la versión de cada paquete se encuentra luego del ==).

El comando pip freeze indica todos los paquetes instalados a nivel del entorno virtual (si el mismo está activo) o del sistema operativo (si el entorno virtual está desactivado o simplemente no lo estás empleando).

Guardar y restaurar dependencias del proyecto

Una de las prácticas que siempre aplico es guardar las dependencias exactas que uso en cada proyecto.
Para hacerlo, ejecuto:

$ pip freeze > requirements.txt

Esto genera un archivo requirements.txt con la lista completa de paquetes y sus versiones. Para restaurar el entorno en otra máquina o después de recrear el venv, simplemente ejecutas:

$ pip install -r requirements.txt

También puedes instalar versiones específicas directamente con el operador ==, por ejemplo:

$ pip install Django==6.0

Por lo tanto, fácilmente puedes crear un ambiente para un proyecto en particular empleando los ambientes virtuales. Como ves, la enorme ventaja es que podemos instalar versiones específicas de nuestros paquetes.

Ya en este punto estamos listos y podemos empezar a desarrollar nuestras aplicaciones en Flask o empezar a desarrollar nuestras aplicaciones en Django.

⚠️ Las Limitaciones de requirements.txt y pip

Video thumbnail

Aunque el flujo clásico de pip + requirements.txt funciona adecuadamente en aplicaciones ligeras desarrolladas con Django, Flask o FastAPI, presenta serias deficiencias en proyectos de mayor escala o en desarrollos multiplataforma.

Para contextualizar estas limitaciones, utilizaremos como ejemplo práctico un proyecto denominado Cerebro Digital. Este sistema actúa como un orquestador de agentes de IA e integra herramientas complejas de procesamiento de video que requieren controladores específicos de hardware, como los de NVIDIA.

Conflictos de Arquitectura y Hardware

Al ejecutar pip freeze, se genera una fotografía exacta y rígida de los paquetes instalados en la máquina actual. Esto incluye dependencias compiladas para un sistema operativo específico o bibliotecas ligadas a un hardware concreto (por ejemplo, CUDA y paquetes de NVIDIA en Linux).

Si este archivo generado en un entorno Linux con GPU NVIDIA se intenta replicar en otra arquitectura (como macOS con chips de Apple), el proceso de instalación fallará. El gestor de paquetes intentará resolver dependencias de hardware que no existen en la nueva plataforma.

Dependencias Circulares y Conflictos Irresolubles

El archivo requirements.txt no distingue entre las dependencias directas del proyecto y sus subdependencias. Al congelar todo el entorno con versiones fijas, se pueden generar bloqueos y dependencias circulares entre paquetes (como ocurre con librerías del tipo browser-use o FFmpeg).

Para mitigar esto en el esquema antiguo, la solución requiere mantener manualmente un archivo requirements.in con las dependencias principales e instalar sobre él, o bien generar archivos independientes como requirements-linux.txt y requirements-mac.txt. Sin embargo, este mantenimiento manual resulta tedioso y propenso a errores.

El Nuevo Estándar: Gestión de Entornos y Dependencias con uv

En el desarrollo de aplicaciones con Python, la gestión tradicional de paquetes mediante pip y los entornos virtuales clásicos puede resultar lenta en proyectos grandes con numerosas dependencias. Para superar estas limitaciones, surge uv, una herramienta de gestión de paquetes escrita en Rust que destaca por su velocidad extrema de ejecución.

uv es un gestor de paquetes y entornos diseñado en Rust que reemplaza a pip, pip-tools y virtualenv en una sola herramienta. Su velocidad de ejecución es entre 10 y 100 veces superior a las herramientas tradicionales y ofrece un sistema de resolución multiplataforma nativo.

En pocas palabras, uv hace con Python lo que npm o composer hacen con JavaScript y PHP respectivamente: gestionar dependencias de forma declarativa, reproducible y sin dolores de cabeza.

Archivos de Configuración: pyproject.toml y uv.lock

uv sustituye la gestión manual de archivos .in y .txt por dos archivos autogenerados y estructurados:

  • pyproject.toml: Es el equivalente a requirements.in (o archivos como package.json y composer.json). Contiene únicamente las dependencias directas del proyecto declaradas de forma limpia.
  • uv.lock: Es el equivalente al archivo de bloqueo (como package-lock.json o composer.lock). Registra la resolución exacta de todas las subdependencias, incluyendo hashes de seguridad y selecciones de binarios (wheels) específicos para cada plataforma (Linux, macOS, Windows).

Gracias a esta estructura, un único archivo uv.lock permite instalar las versiones correctas tanto en un entorno Linux con NVIDIA como en un entorno macOS, ignorando las dependencias de hardware no compatibles en cada caso.

Instalación y Puesta en Marcha de uv

Aunque el uso de uv es opcional y en muchos entornos académicos se puede seguir utilizando el flujo clásico con pip, este gestor representa el nuevo estándar de la industria. Su instalación puede realizarse de distintas formas según el sistema operativo:

  • macOS y Linux: Se recomienda utilizar el gestor de paquetes Homebrew mediante el comando brew install uv, o bien el instalador oficial mediante script de consola.
  • Windows: Puede instalarse a través de PowerShell utilizando los comandos oficiales de descarga.
  • Métodos alternativos: Es posible instalarlo globalmente mediante pip install uv (aunque no es la opción ideal para evitar contaminar el entorno global del sistema) o utilizando pipx como solución intermedia en entornos aislados.

https://docs.astral.sh/uv/getting-started/installation/

Si no sabes como lo instalastes, ejecuta which uv 

Una vez completada la instalación, se puede verificar su correcto funcionamiento ejecutando en la terminal:

uv --version

Comandos Principales: pip vs uv

La siguiente tabla resume las diferencias operativas entre el flujo tradicional y el flujo moderno con uv:

AcciónFlujo Clásico (pip / pip-tools)Flujo Moderno (uv)
Crear entorno virtualpython3 -m venv .venvuv init (lo crea automáticamente)
Añadir dependenciapip install <pkg> y edición manualuv add <pkg>
Eliminar dependenciapip uninstall <pkg>uv remove <pkg>
Sincronizar entornopip install -r requirements.txtuv sync
Ejecutar comandospython script.py (con entorno activo)uv run script.py
Exportar dependenciaspip freeze > requirements.txtAutomático en uv.lock

Migración Práctica a uv

Para migrar un proyecto existente al nuevo esquema con uv, sigue estos pasos:

  1. Eliminar el entorno virtual anterior (.venv) y los archivos requirements.txt antiguos.
  2. Inicializar el proyecto con uv para generar la estructura base:

    uv init
  3. Añadir las dependencias principales del proyecto. uv actualizará automáticamente pyproject.toml y resolverá el archivo uv.lock:

    uv add django

    O si tu proyecto usa FastAPI:

    uv add fastapi uvicorn
  4. Sincronizar el entorno de desarrollo en cualquier máquina. El comando detectará el sistema operativo actual y descargará únicamente los binarios compatibles:

    uv sync

Una vez completada la sincronización, los comandos de la aplicación se ejecutan anteponiendo uv run, asegurando que se utilice el entorno virtual administrado de forma transparente:

uv run python manage.py runserver

O para FastAPI:

uv run uvicorn main:app --reload

Opcional: Crear el Ambiente Virtual mediante Visual Studio Code

Esta es la opción que te recomiendo si prefieres no usar la terminal. Crea el ambiente virtual directamente desde una instancia de VS Code (con esta opción NO estas empleando UV si no la pip).

  • Abrir Carpeta: Abre una instancia limpia de VS Code (Ctrl + Shift + N). Arrastra o abre la carpeta de tu proyecto.
  • Crear Ambiente: Presiona Ctrl + Shift + P.
  • Busca: Python: Create Environment.
  • Selecciona el proveedor: Venv (o Virtualenv).
  • Selecciona tu Python: El Python que tienes instalado a nivel del sistema operativo.

VS Code lo hará todo por ti. La gran ventaja es que no tenemos que lidiar con la selección del intérprete ni con problemas de reconocimiento. Una vez creado, abre la terminal en VS Code: verás que te aparece el nombre del ambiente virtual entre paréntesis, indicando que está activo. Si ejecutas pip freeze, verás que no aparece absolutamente nada (entorno limpio).

Opcional: Seleccionar intérprete de Python en Visual Studio Code

La mayoría de las veces VS Code no reconocerá automáticamente el intérprete de Python configurado en el ambiente virtual, sino que tomará el instalado a nivel global del sistema operativo. Esto trae el inconveniente de que aparecen advertencias en las importaciones de la aplicación:

Seleccionar intérprete

Y, por lo tanto, no es posible acceder al detalle de los módulos importados. Para solucionar esto, debemos indicarle a VS Code que el intérprete que debe usar es el del ambiente virtual —donde tenemos instalado todo el ecosistema del proyecto— y no el del Sistema Operativo.

Presiona la combinación de teclas Command/Control + Shift + P y busca por "Seleccionar intérprete":

Ventana para seleccionar intérprete con Command/Control + Shift + P

Y selecciona el de tu ambiente virtual desde la opción de "Escriba la ruta de acceso del intérprete":

Seleccionar Python para el intérprete

En caso de que, con el hecho de seleccionar el intérprete, aún siga mostrando la advertencia de "No se ha podido resolver la importación X", puedes probar crear un proyecto desde cero mediante VS Code: abre una instancia limpia de VS Code, luego Command/Control + Shift + P y busca por "Crear ambiente":

Crear ambiente virtual

Sigue los pasos que te indica el editor: selecciona el entorno, coloca Venv:

Seleccionar venv

Luego, puede que te indique que coloques el área de trabajo:

Seleccionar área de trabajo

Y vuelves al paso 1: Command/Control + Shift + P y busca por "Crear ambiente". En esta oportunidad, debería preguntarte por el intérprete que quieras emplear:

Seleccionar intérprete de Python

Y con esto debería reconocerse los paquetes instalados a nivel del ambiente virtual.

Consejos finales para mantener tu entorno limpio y estable

  • Crea un entorno virtual por cada proyecto.
  • Evita instalar paquetes globalmente.
  • Usa requirements.txt (con pip) o pyproject.toml (con uv) para controlar versiones.
  • Si un entorno se corrompe o da errores, elimínalo y créalo de nuevo: ¡es rápido y seguro!
  • Mantén Python actualizado para evitar incompatibilidades.
  • Para proyectos nuevos, considera adoptar uv desde el inicio: te ahorrará muchos dolores de cabeza a futuro.

En mi experiencia, usar entornos virtuales te evita dolores de cabeza y te da control total sobre tus proyectos en Django, Flask, FastAPI o cualquier otro framework de Python.

Preguntas frecuentes sobre entornos virtuales en Python

  • ¿Qué es un entorno virtual en Python?
    Es un espacio aislado donde puedes instalar dependencias sin afectar al sistema principal.
  • ¿Por qué usar un entorno virtual con Django, Flask o FastAPI?
    Porque estos frameworks dependen de muchas librerías que pueden variar de versión entre proyectos.
  • ¿Qué diferencia hay entre venv, virtualenv y uv?
    venv viene con Python 3; virtualenv es una herramienta externa más antigua pero aún útil; uv es el nuevo estándar, más rápido y con resolución multiplataforma nativa.
  • ¿Cómo activo mi entorno virtual?
    Con pip: en Windows myenv\Scripts\activate, en Linux/macOS source myenv/bin/activate.
    Con uv: no necesitas activar nada manualmente; usa uv run y el entorno se gestiona automáticamente.
  • ¿Cómo guardo mis dependencias?
    Con pip: pip freeze > requirements.txt.
    Con uv: se gestiona automáticamente en pyproject.toml y uv.lock.
  • ¿Debería migrar mi proyecto a uv?
    Si tu proyecto tiene dependencias complejas, trabaja en múltiples plataformas o simplemente quieres modernizar tu flujo de trabajo, sí, definitivamente vale la pena. Para proyectos simples, pip sigue siendo válido.

Conclusión

Crear un entorno virtual en Python para Django, Flask o FastAPI no es complicado, y una vez que entiendes su propósito, se vuelve parte natural de tu flujo de trabajo.

El ecosistema ha evolucionado: de virtualenv pasamos a venv, y ahora uv se posiciona como el nuevo estándar que unifica la gestión de entornos y dependencias en una sola herramienta rápida, moderna y multiplataforma.

En mi caso, fue un antes y un después en la organización de mis proyectos. Te animo a que lo pruebes tú mismo: en pocos minutos tendrás tu propio entorno listo para crear cualquier aplicación en Python.

El siguiente paso es conocer sobre qué es Django framework.

Aprende a crear entornos virtuales en Python con venv, pip y uv. Guía paso a paso para aislar dependencias en proyectos Django 6, Flask y FastAPI.


Únete a la comunidad de desarrolladores que han decidido dejar de picar código y empezar a construir productos reales. Recibe mis mejores trucos de arquitectura cada semana:

Acepto recibir anuncios de interes sobre este Blog.