Instalación: el entorno virtual y el primer proyecto

Hasta aquí, todo el curso se ha ejecutado con lo que trae Python de fábrica. Ciento cuarenta y seis lecciones sin instalar nada es una rareza que ha merecido la pena, porque los ejemplos funcionan en cualquier máquina y porque obliga a conocer bien la biblioteca estándar. Se acabó: Django no viene con Python y hay que instalarlo.

La lección 30 del módulo 1 ya explicó qué es un entorno virtual y la 22 del módulo 2 lo usó para empaquetar una herramienta. Aquí se repasa lo justo y se va al grano, porque lo que de verdad da problemas no es crear el entorno, es olvidarse de activarlo.

Por qué un entorno virtual y no pip install django a secas#

Instalar Django en el Python del sistema funciona el primer día y estorba a partir del segundo, por tres motivos concretos:

• Un proyecto no usa la última versión de todo, usa una. Cuando tengas dos proyectos, uno de hace dos años con Django 5.2 y el nuevo con 6.1, no caben los dos en la misma instalación. Y el de hace dos años no se actualiza porque sí, se actualiza cuando hay tiempo.
• Nadie sabe qué necesita tu proyecto. Con todo instalado en el mismo sitio, tu proyecto funciona porque en esa máquina está lo que hace falta, mezclado con veinte cosas de otros proyectos. El día que hay que ponerlo en un servidor, no hay forma de saber qué había que copiar.
• En macOS y en Linux hay un Python que es del sistema operativo. Lo usan utilidades del propio sistema, y tocarlo con pip puede romperlas. Las distribuciones modernas y Homebrew directamente te lo impiden, con un error que dice externally-managed-environment.

Un entorno virtual es una carpeta con su propio Python y sus propios paquetes. No es magia ni es una máquina virtual: son unos enlaces y una variable de entorno.

Crear el entorno#

Colócate donde vayas a tener el proyecto y crea una carpeta para él:

mkdir agenda
cd agenda

La orden que crea el entorno es la misma en los tres sistemas:

python3 -m venv .venv

En Windows, casi siempre python en lugar de python3:

python -m venv .venv

El nombre .venv es una convención muy extendida. Empieza por punto, así que no estorba al listar, y los editores lo reconocen solos: tanto VS Code como PyCharm detectan una carpeta .venv dentro del proyecto y la usan sin que les digas nada.

Activarlo sí cambia según el sistema:

Sabrás que ha funcionado porque el prompt cambia y aparece (.venv) delante. Para salir, deactivate, en todos los sistemas.

Instalar Django#

Con el entorno activado:

pip install django

Para el curso conviene fijar la versión, y así te sale exactamente lo mismo que aquí:

pip install "django==6.1.1"

Installing collected packages: sqlparse, asgiref, django
Successfully installed asgiref-3.12.1 django-6.1.1 sqlparse-0.6.0

Han entrado tres paquetes y tú pediste uno. asgiref y sqlparse son dependencias de Django: cosas que Django necesita y que pip ha traído por su cuenta. La primera se ocupa de la parte asíncrona y la segunda da formato al SQL que verás en la lección de migraciones. No hay que saber nada más de ellas, pero conviene no asustarse al verlas.

pip list

Package  Version
-------- -------
asgiref  3.12.1
Django   6.1.1
pip      26.2.1
sqlparse 0.6.0

Cuatro paquetes y nada más. Eso es lo que da un entorno virtual: saber exactamente lo que hay.

Los dos fallos de no activar el entorno#

Merece la pena provocarlos ahora, con calma, porque cuando aparezcan de verdad lo harán en mitad de otra cosa.

El primero: ImportError al ejecutar manage.py. Abre una terminal nueva, no actives nada y ejecuta cualquier orden del proyecto. Django está instalado, pero no en el Python que se está usando:

ImportError: Couldn't import Django. Are you sure it's installed and available on your
PYTHONPATH environment variable? Did you forget to activate a virtual environment?

Es de los pocos mensajes de error que te dicen la solución con todas las letras, y está en manage.py, escrito a mano por la gente de Django precisamente porque sabían que esto iba a pasar mucho. Actívalo y ya está.

El segundo es peor, porque no da ningún error. Si alguna vez instalaste Django fuera de un entorno virtual, la orden django-admin existe en el sistema. Sin activar el entorno:

which django-admin

/Users/erwin/Library/Python/3.14/bin/django-admin

Esa no es la del proyecto. Es otra instalación, probablemente de otra versión, y va a funcionar: creará el proyecto, arrancará el servidor y te dará errores incomprensibles el día que uses algo que en esa versión no existe. La comprobación que resuelve la duda en dos segundos:

which django-admin      # en Windows: where django-admin
python -c "import django; print(django.__file__)"

Si las dos rutas no pasan por tu carpeta .venv, el entorno no está activado.

Crear el proyecto#

Con el entorno activado y Django dentro:

django-admin startproject agenda .

No imprime nada. Eso es buena señal.

El punto del final importa mucho y es la primera decisión de forma del módulo. Con el punto, Django crea el paquete de configuración dentro de la carpeta en la que estás. Sin el punto, crea una carpeta nueva llamada agenda y mete todo dentro, y como tú ya estabas en una carpeta llamada agenda, acabas con agenda/agenda/agenda/, tres niveles con el mismo nombre. Funciona, pero cada vez que abras un fichero tendrás que pensar en cuál de las tres estás.

Esto es lo que ha aparecido:

agenda/
  .venv/            El entorno virtual, que ya estaba
  agenda/           La configuración del proyecto
    __init__.py
    settings.py     Los ajustes
    urls.py         Las direcciones
    asgi.py         Punto de entrada para servidores asíncronos
    wsgi.py         Punto de entrada para servidores clásicos
  manage.py         Por aquí se ejecuta todo

Cada fichero tiene su explicación en la lección siguiente, que es solo para eso. Lo que hace falta ahora es probar que funciona:

python manage.py runserver

Abre http://127.0.0.1:8000/ y verás una página con un cohete despegando y el texto "The install worked successfully! Congratulations!". Se para con Ctrl + C.

Anotar lo que hace falta#

Un entorno virtual no se comparte ni se sube a ningún sitio: pesa, y tiene rutas absolutas de tu máquina dentro. Lo que se comparte es la lista de lo que hay que instalar. Se genera sola:

pip freeze > requirements.txt

asgiref==3.12.1
Django==6.1.1
sqlparse==0.6.0

Con ese fichero, cualquiera —incluido tú mismo dentro de un año, o el servidor donde acabe el proyecto— reconstruye el entorno exacto:

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Fíjate en que pip freeze lista también las dependencias de las dependencias, con la versión clavada. Es lo que se quiere: no se trata de decir "algo de Django", se trata de reproducir lo que funcionaba.