Django desde cero: Guía definitiva para instalarlo usando venv o uv

Si alguna vez te sentiste perdido entre versiones de Python, dependencias que se rompen y entornos que parecen una caja de Pandora, este post es para vos. Instalar Django parece una tarea de cinco minutos, pero si no tomás las decisiones correctas desde el principio, vas a terminar con un desastre de paquetes globales que te va a hacer la vida imposible.

En este artículo, vamos a dejar de lado las malas prácticas y vamos a enfocarnos en cómo preparar tu terreno de juego de manera profesional. Te voy a guiar paso a paso para que configures tu entorno de desarrollo usando dos caminos: el clásico y confiable venv, y la nueva joya de la corona de la comunidad Python: uv.

¿Por qué no deberías instalar Django globalmente?

Antes de tirar el primer comando, hablemos de por qué no tenés que hacer pip install django directamente en tu terminal sin más.

Cuando instalás algo de forma global, ese paquete queda disponible para todo tu sistema. Esto suena cómodo, pero es una trampa mortal. Imaginate que tenés un proyecto viejo que usa Django 3.2 y empezás uno nuevo que necesita Django 5.0. Si instalás Django globalmente, la nueva versión va a pisar a la vieja y tu proyecto anterior va a dejar de funcionar.

Los entornos virtuales solucionan esto. Crean una burbuja aislada para cada proyecto. Lo que pase adentro de esa burbuja, se queda adentro. Esto te da la libertad de tener 20 proyectos con 20 versiones distintas de Django sin que se peleen entre ellos.

Opción 1: El camino tradicional con venv

venv es el módulo estándar que viene con Python. Es robusto, no requiere instalar herramientas extra (si ya tenés Python) y es el estándar de la industria desde hace años. Si querés ir a lo seguro, este es tu camino.

Paso 1: Crear la carpeta de tu proyecto

Primero, organicemos la casa. Creá un directorio para tu nuevo proyecto y metete ahí.

mkdir mi_proyecto_django
cd mi_proyecto_django

Paso 2: Crear el entorno virtual

Ahora vamos a crear la "burbuja". El comando estándar es python -m venv <nombre_del_entorno>. Por convención, solemos llamarlo .venv para que sea un archivo oculto y no estorbe en la vista.

python -m venv .venv

Paso 3: Activar el entorno

Acá es donde la mayoría de la gente se traba. El comando de activación cambia según tu sistema operativo.

En Linux o macOS:

source .venv/bin/activate

En Windows (PowerShell):

.\.venv\Scripts\Activate.ps1

Salida esperada:
Una vez activado, vas a notar que el nombre de tu entorno aparece entre paréntesis al principio de tu línea de comandos, algo así:

(.venv) usuario@maquina:~/mi_proyecto_django$

Paso 4: Instalar Django

Con el entorno activo, ya podés usar pip con total seguridad. Todo lo que instales acá se guardará dentro de la carpeta .venv.

pip install django

Salida esperada:

Collecting django
  Downloading django-5.0.x-py3-none-any.whl (...
Installing collected packages: asgiref, sqlparse, django
Successfully installed django-5.0.x

Paso 5: Verificar la instalación

No te quedes con la duda. Verificá qué versión tenés instalada.

python -m django --version

Salida esperada:

5.0.x

Opción 2: El camino de la velocidad con uv

Si sos de los que odian esperar a que pip descargue y resuelva dependencias, tenés que conocer uv. Es una herramienta escrita en Rust que es extremadamente rápida. Es, literalmente, un reemplazo para pip, pip-tools y venv que hace todo de una.

¿Por qué usar uv?

• Velocidad: Es órdenes de magnitud más rápido que pip.
• Todo en uno: Maneja la instalación de Python, la creación de entornos y la gestión de paquetes.
• Resolución de dependencias: Es mucho más inteligente para evitar conflictos.

Paso 1: Instalar uv

(Este paso lo hacés una sola vez en tu máquina. No lo incluimos en el entorno del proyecto).

# En macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# En Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

Paso 2: Inicializar el proyecto y el entorno

Con uv, no necesitás andar creando carpetas manualmente y después activando. Podés hacer todo de un tirón. Entrá a tu carpeta de proyecto y ejecutá:

cd mi_proyecto_uv
uv venv

Esto te crea un entorno virtual de forma instantánea.

Paso 3: Instalar Django con uv

En lugar de pip install, usás uv pip install (o simplemente uv add si estás usando la gestión de proyectos de uv).

uv pip install django

Salida esperada:
Verás que la instalación termina casi antes de que puedas parpadear. La salida es similar a la de pip, pero mucho más limpia y veloz.

Paso 4: Ejecutar Django sin siquiera "activar" (Truco pro)

Una de las mejores cosas de uv es que podés ejecutar comandos dentro del entorno sin tener que hacer source .venv/bin/activate. Usás uv run.

uv run django-admin startproject mi_sitio .

Esto crea la estructura básica de Django asegurándose de que se use el Django que instalaste en el entorno virtual.

Comparativa rápida: ¿Cuál elegir?

Buenas prácticas y errores comunes

Para que no te rompas la cabeza, seguí estos consejos:

1. ¡Nunca subas el entorno virtual a Git! El directorio .venv es pesado y específico de tu sistema operativo. Agregá siempre .venv/ a tu archivo .gitignore. Lo que tenés que subir es el archivo de requerimientos (requirements.txt o pyproject.toml).
2. Generá siempre tus requerimientos: Una vez que instalaste Django, corré pip freeze > requirements.txt. Así, cuando un compañero descargue tu proyecto, solo tendrá que hacer pip install -r requirements.txt para tener exactamente lo mismo que vos.
3. Ojo con el nombre del comando: En algunos sistemas, el comando es python3 en lugar de python. Si python --version te da error, probá con python3.
4. No mezcles: Si empezás un proyecto con uv, tratá de seguir con uv. Mezclar gestores de paquetes en un mismo entorno puede traer dolores de cabeza con las versiones de las librerías.

Conclusión

Instalar Django es solo el primer paso de un largo camino de aprendizaje. La clave para ser un buen desarrollador no es solo saber programar, sino saber gestionar tus herramientas.

Si estás arrancando y querés entender cómo funciona el ecosistema Python, usá venv. Si ya tenés un poco de experiencia y querés que tu flujo de trabajo vuele, pasate a uv sin dudarlo.

¿Ya probaste alguno de estos métodos? ¿Tuviste algún error raro al activar el entorno? Dejamelo en los comentarios y lo vemos juntos. ¡Éxitos con ese nuevo proyecto!