Crear un Proyecto en Django - Tutorial

Django está pensado para trabajar por módulos: cada app agrupa una funcionalidad concreta (por ejemplo, usuarios, blog o catálogo) y puede desarrollarse, probarse y mantenerse de forma independiente. Esa separación facilita que el proyecto crezca sin volverse complicado.

En términos prácticos, el proyecto contiene varias apps; las vistas generan el contenido, las URLs exponen ese contenido en direcciones web, las plantillas construyen el HTML que envía el servidor y los archivos estáticos (CSS, JS, imágenes) definen el aspecto y la interactividad en el navegador. Más abajo veremos cómo organizar todas estas piezas.

Esta guía explica, paso a paso, cómo crear un proyecto en macOS, levantarlo localmente, agregar una app web, organizar templates y estáticos, y poner en marcha lo básico para empezar a desarrollar. Está escrita en tono pedagógico y con ejemplos claros.

1. Preparar el entorno

Django está escrito en Python, así que antes de empezar debemos asegurarnos de tener Python y las herramientas básicas.

Python es el lenguaje que usaremos para programar la lógica del sitio. pip es la herramienta que instala las librerías que necesitamos.

Comprueba tu versión con:

python3 --version

Si ves algo como Python 3.12.3, perfecto.

También comprueba pip (la herramienta de paquetes):

pip3 --version

2. Crear una carpeta para tu proyecto

Es buena práctica tener una carpeta donde guardas todos tus proyectos para no perderlos.

cd ~
mkdir proyectos_django
cd proyectos_django
mkdir mi_primer_proyecto
cd mi_primer_proyecto

Piensa en esta carpeta como la raíz del proyecto: aquí estarán manage.py, la carpeta del proyecto y las apps.

3. Crear un entorno virtual (venv)

Los entornos virtuales nos permiten instalar librerías sin afectar el resto del sistema; así cada proyecto mantiene sus propias dependencias.

Crear el entorno virtual:

python3 -m venv venv

Activarlo:

source venv/bin/activate

Si ves (venv) al inicio de la línea, significa que estás usando la caja de herramientas del proyecto.

Para salir del entorno cuando termines:

deactivate

Consejo: siempre activa el venv antes de instalar paquetes con pip para no mezclar dependencias entre proyectos. Fíjate en eso.

4. Instalar Django dentro del entorno

Con el venv activado, instala Django:

pip install django

Para confirmar la instalación:

python -m django --version

Verás un número como 5.0.2 (o parecido). Esto significa que Django está listo.

Nota: instalar Django proporciona las herramientas principales (ruteo, ORM, sistema de plantillas, panel de administración) que usarás para construir tu aplicación.

5. Crear tu proyecto Django

Vamos a crear el proyecto en la carpeta actual. El . al final indica “aquí mismo”.

django-admin startproject mi_proyecto .

Breve explicación:

• mi_proyecto/ → contiene settings.py, urls.py y la configuración global.
• manage.py → la herramienta para ejecutar tareas (migraciones, arrancar el servidor, etc.).
• venv/ → tu entorno virtual con las librerías instaladas.

Estructura típica:

mi_primer_proyecto/
├── manage.py
├── mi_proyecto/
│   ├── __init__.py
│   ├── asgi.py
│   ├── settings.py
│   ├── urls.py
│   └── wsgi.py
└── venv/

Después de esto tendrás la estructura base del proyecto y podrás empezar a agregar apps que implementen funcionalidades concretas.

6. Aplicar las migraciones iniciales y levantar el servidor

Django necesita crear tablas en la base de datos para cosas como usuarios y sesiones. Eso se hace con “migraciones”.

python manage.py migrate

Levanta el servidor de desarrollo:

python manage.py runserver

Abre el navegador en:

http://127.0.0.1:8000/

Si ves la pantalla de bienvenida de Django, ¡genial! Para detener el servidor presiona Ctrl + C.

Las migraciones crean las tablas y relaciones necesarias en la base de datos; runserver pone en marcha un servidor de desarrollo para ver tu sitio localmente.

Ahora para poder visualizar el proyecto, crearemos un homepage. Para eso haremos una app llamada web que mostrará la página principal.

7. Crear tu primera app: web

Una “app” en Django es un módulo que agrupa modelos, vistas, URLs y recursos relacionados con una funcionalidad concreta (por ejemplo, blog, usuarios o tienda). Crearemos web para mostrar la página principal.

python manage.py startapp web

Estructura de la app:

web/
├── admin.py
├── apps.py
├── models.py
├── tests.py
├── views.py
└── migrations/

views.py es donde defines las funciones o clases que generan las respuestas HTTP. models.py define las estructuras de datos que se almacenarán en la base de datos.

8. Registrar la app en settings.py

Abre mi_proyecto/settings.py y busca la lista INSTALLED_APPS. Añade 'web', para que Django conozca la app.

INSTALLED_APPS = [
    'django.contrib.admin',
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.messages',
    'django.contrib.staticfiles',

    'web',  # nuestra app
]

Con esto Django cargará la app y sus archivos (migraciones, admin, etc.).

9. Crear la primera vista

Abre web/views.py y añade una función que muestre la página principal:

from django.shortcuts import render

def home(request):
    contexto = {
        "titulo": "mi primer proyecto en django",
        "mensaje": "esta es una vista renderizada desde la app web.",
    }
    return render(request, "web/home.html", contexto)

Una vista recibe la petición (request) y devuelve una respuesta (por ejemplo, renderizando una plantilla). El contexto es un diccionario con datos que la plantilla usará para mostrar información dinámica.

10. Conectar la vista a una ruta (URLs)

10.1. URLs del proyecto

Abre mi_proyecto/urls.py y añade una línea para incluir las URLs de la app web:

from django.contrib import admin
from django.urls import path, include

urlpatterns = [
    path('admin/', admin.site.urls),
    path('', include('web.urls')),
]

10.2. URLs de la app

Crea web/urls.py con las rutas de la app:

from django.urls import path
from . import views

urlpatterns = [
    path('', views.home, name='home'),
]

Las URLs funcionan como direcciones en un mapa: asocian rutas a funciones o vistas. La ruta '' (cadena vacía) apunta a la página principal /.

11. Crear la carpeta de templates

Las plantillas (templates) son los archivos HTML que muestran contenido. Crea la carpeta global de templates y una subcarpeta para web:

mkdir templates
mkdir -p templates/web

Estructura:

templates/
└── web/
    └── home.html

Las plantillas son los archivos HTML que construyen la interface visible y se combinan con datos enviados desde las vistas para generar páginas dinámicas.

12. Activar templates en settings.py

Edita TEMPLATES para añadir la carpeta global templates:

TEMPLATES = [
    {
        "BACKEND": "django.template.backends.django.DjangoTemplates",
        "DIRS": [BASE_DIR / "templates"],
        "APP_DIRS": True,
        # ...
    },
]

Esto le indica a Django dónde buscar los archivos HTML que vas a mostrar.

13. Plantilla home.html

templates/web/home.html:

<!doctype html>
<html lang="es">
<head>
    <meta charset="utf-8">
    <title>{{ titulo }}</title>
    <link rel="stylesheet" href="{% static 'css/estilos.css' %}">
</head>
<body>
    <h1>{{ titulo }}</h1>
    <p>{{ mensaje }}</p>
    <!-- Consejo: las llaves dobles {{ }} muestran datos que vienen del servidor -->
</body>
</html>

En la plantilla {{ titulo }} y {{ mensaje }} se reemplazarán por los valores del contexto enviados desde la vista.

14. Configurar archivos estáticos

Los archivos estáticos (CSS, imágenes, JavaScript, fuentes) son recursos que el navegador descarga y usa tal como están. A continuación una descripción de los tipos más comunes y su función:

• CSS: define la presentación visual (colores, tamaños, márgenes, tipografías).
• JavaScript (JS): añade interactividad en el cliente (eventos, cambios dinámicos, llamadas a APIs).
• Imágenes: logos, íconos y fotos que se muestran en la interfaz.
• Fuentes y otros recursos: tipografías, SVGs u otros activos que el navegador necesita.

Organización recomendada dentro de cada app:

web/static/web/css/
web/static/web/js/
web/static/web/img/

Crear la carpeta y el CSS de ejemplo:

mkdir -p web/static/web/css

web/static/web/css/estilos.css:

body {
    font-family: system-ui, -apple-system, sans-serif;
    padding: 2rem;
    background: #f4f5f7;
}

En settings.py configura las rutas estáticas:

STATIC_URL = "static/"

STATICFILES_DIRS = [
    BASE_DIR / "web/static",
]

Puntos importantes:

• En desarrollo (DEBUG=True) el comando runserver sirve automáticamente los archivos estáticos de las apps y de STATICFILES_DIRS.
• En producción, fíjate en ejecutar python manage.py collectstatic para copiar todos los archivos estáticos en un único directorio (STATIC_ROOT) y servirlos desde un servidor web (Nginx, CDN) optimizado.
• Para archivos subidos por usuarios (imágenes, documentos) usa MEDIA_URL y MEDIA_ROOT y configura las rutas en settings.py y en urls.py según la documentación.

Organizar bien los estáticos ayuda a mantener el sitio ágil y facilita cacheo y distribución por CDN en producción.

15. Ejecutar el servidor

python manage.py runserver

Ir a:

http://127.0.0.1:8000/

¡Y listo! Tu web debería mostrarse con la plantilla que creaste.

Estructura final

mi_primer_proyecto/
├── manage.py
├── mi_proyecto/
│   ├── settings.py
│   ├── urls.py
│   ├── asgi.py
│   ├── wsgi.py
│   └── __init__.py
├── web/
│   ├── views.py
│   ├── urls.py
│   ├── static/
│   │   └── web/
│   │       └── css/
│   │           └── estilos.css
│   └── migrations/
├── templates/
│   └── web/
│       └── home.html
└── venv/

Django fomenta la modularidad —puedes añadir apps como módulos independientes que encapsulan modelos, vistas, URLs, templates y archivos estáticos— y también subdividir responsabilidades dentro de cada app si lo necesitas. Esta forma de trabajar facilita entender, probar y mantener el código: agregar una nueva funcionalidad suele reducirse a crear una app, desarrollar sus modelos y vistas, y añadirla a INSTALLED_APPS. Ahora que tienes la base, prueba crear otra app (por ejemplo blog), define sus modelos y rutas, y fíjate cómo Django mantiene cada parte separada pero conectada.