Aprenderemos por ejemplo.
A lo largo de este tutorial, iremos paso a paso en la creación de una aplicación básica de encuestas.
Estará compuesta de dos partes:
Un sitio público que permite a las personas ver encuestas y votar en ellas.
Un sitio administrativo que te permite agregar, cambiar y eliminar encuestas.
Supondremos que ya tienes instalado Django . Puedes comprobar si Django está instalado y qué versión estando ejecutando el siguiente comando en una ventana de shell (indicada por el prefijo $):
$ python -m django --version
Si Django está instalado, deberías ver la versión de tu instalación. Si no lo está, obtendrás un error que dice «No module named django».
Este tutorial está escrito para Django 5.2, que admite Python 3.10 y posterior. Si la versión de Django no coincide, puedes referirte al tutorial para tu versión de Django utilizando el selector de versión en la esquina inferior derecha de esta página o actualizar a la última versión. Si estás usando una versión anterior de Python, revisa ¿Qué versión de Python puedo usar con Django? para encontrar una versión compatible de Django.
¿Dónde obtener ayuda:
Si tienes problemas al seguir este tutorial, por favor dirígete a la sección Ayuda del FAQ.
Si es la primera vez que utilizas Django, deberás ocuparte de algunas configuraciones iniciales. En concreto, necesitarás generar automáticamente algún código que establezca una proyecto de Django – una colección de configuraciones para una instancia de Django, incluyendo la configuración de base de datos, opciones específicas de Django y ajustes específicos de aplicación.
Desde la línea de comandos, cd en un directorio donde desees almacenar tu código y crea un nuevo directorio llamado djangotutorial. (El nombre de este directorio no importa a Django; puedes renombrarlo como prefieras.)
$ mkdir djangotutorial
Luego, ejecuta el siguiente comando para crear una nueva instancia de proyecto de Django:
$ django-admin startproject mysite djangotutorial
Esto creará un proyecto llamado mysite dentro del directorio djangotutorial. Si no funcionó, consulta Problemas al ejecutar django-admin.
Nota
You necesitarás evitar nombrar proyectos con componentes de Python o Django incorporados. En particular, esto significa que debes evitar usar nombres como django (que conflictuará con Django mismo) o test (que conflictúa con un paquete de Python incorporado).
Vamos a ver qué creó startproject:
djangotutorial/
manage.py
mysite/
__init__.py
settings.py
urls.py
asgi.py
wsgi.py
Estos archivos son:
manage.py: Una utilidad de línea de comandos que te permite interactuar con este proyecto Django de diversas maneras. Puedes leer todos los detalles sobre manage.py en django-admin y manage.py.
mysite/: Un directorio que es el paquete Python real para tu proyecto. Su nombre es el nombre del paquete Python que necesitarás usar para importar cualquier cosa dentro de él (por ejemplo, mysite.urls).
mysite/__init__.py: Un archivo vacío que le dice a Python que este directorio debe considerarse un paquete Python. Si eres principiante en Python, lee más sobre los paquetes en la documentación oficial de Python.
mysite/settings.py: Configuración/configuraciones para este proyecto Django. Configuración de Django te dirá todo sobre cómo funcionan las configuraciones.
mysite/urls.py: Las declaraciones de URL para este proyecto Django; una «tabla de contenido» de tu sitio web impulsado por Django. Puedes leer más sobre URLs en Dispatcher de URL.
mysite/asgi.py: Un punto de entrada para servidores web ASGI compatibles que sirvan tu proyecto. Ver Cómo desplegar con ASGI para obtener más detalles.
mysite/wsgi.py: Un punto de entrada para servidores web WSGI compatibles que sirvan tu proyecto. Ver Cómo desplegar con WSGI para obtener más detalles.
Vamos a verificar que tu proyecto Django funciona correctamente. Cambia al directorio djangotutorial, si aún no lo has hecho, y ejecuta los siguientes comandos:
$ python manage.py runserver
Verás la siguiente salida en la línea de comandos:
Performing system checks... System check identified no issues (0 silenced). You have unapplied migrations; your app may not work properly until they are applied. Run 'python manage.py migrate' to apply them. mayo 31, 2026 - 15:50:53 Django version 5.2, using settings 'mysite.settings' Starting development server at http://127.0.0.1:8000/ Quit the server with CONTROL-C. WARNING: This is a development server. Do not use it in a production setting. Use a production WSGI or ASGI server instead. For more information on production servers see: https://docs.djangoproject.com/en/5.2/howto/deployment/
Nota
Ignora el aviso sobre migraciones de base de datos sin aplicar por ahora; nos ocuparemos de la base de datos más adelante.
Ahora que el servidor está funcionando, visita http://127.0.0.1:8000/ con tu navegador web. Verás una página «¡Felicidades!», con un cohete despegando. ¡Ha funcionado!
Has iniciado el servidor de desarrollo de Django, un servidor web ligero escrito puramente en Python. Lo hemos incluido con Django para que puedas desarrollar cosas rápidamente, sin tener que preocuparte por configurar un servidor de producción – como Apache – hasta estar listo para la producción.
Es el momento adecuado para señalar: no uses este servidor en nada que se asemeje a un entorno de producción. Está destinado únicamente al uso mientras desarrollas. (Estamos en el negocio de crear frameworks web, no servidores web.)
(Para servir el sitio en un puerto diferente, consulta la referencia runserver. )
Recarga automática del servidor runserver
El servidor de desarrollo recarga automáticamente el código Python para cada solicitud según sea necesario. No necesitas reiniciar el servidor para que los cambios en el código tengan efecto. Sin embargo, algunas acciones como agregar archivos no desencadenan un reinicio, por lo que tendrás que reiniciar el servidor en estos casos.
Ahora que tienes configurado tu entorno – un «proyecto» – estás listo para empezar a trabajar.
Cada aplicación que escribas en Django consiste en una paqueta Python que sigue una convención determinada. Django viene con una utilidad que genera automáticamente la estructura de directorios básica de una app, así que puedes enfocarte en escribir código en lugar de crear directorios.
Proyectos vs. apps
¿Cuál es la diferencia entre un proyecto y una app? Una app es una aplicación web que hace algo – por ejemplo, un sistema de blog, un banco de datos de registros públicos o una pequeña aplicación de encuesta. Un proyecto es una colección de configuración y apps para un sitio web en particular. Un proyecto puede contener múltiples apps. Una app puede estar en múltiples proyectos.
Tus apps pueden vivir en cualquier lugar de tu ruta Python. En este tutorial, crearemos nuestra aplicación de encuesta dentro del directorio djangotutorial.
Para crear tu app, asegúrate de estar en el mismo directorio que manage.py y ejecuta esta orden:
$ python manage.py startapp polls
Eso creará un directorio polls, que se organiza como sigue:
polls/
__init__.py
admin.py
apps.py
migrations/
__init__.py
models.py
tests.py
views.py
Esta estructura de directorios albergará la aplicación de encuesta.
Let’s write the first view. Open the file polls/views.py y pón el siguiente código Python en él:
polls/views.py¶from django.http import HttpResponse
def index(request):
return HttpResponse("Hello, world. You're at the polls index.")
Esta es la vista más básica posible en Django. Para acceder a ella mediante un navegador, necesitamos mapearla a una URL - y para ello debemos definir una configuración de URLs, o «URLconf» por su nombre corto. Estas configuraciones de URLs se definen dentro de cada aplicación Django, y son archivos Python llamados urls.py.
Para definir un URLconf para la aplicación polls, crea un archivo polls/urls.py con el siguiente contenido:
polls/urls.py¶from django.urls import path
from . import views
urlpatterns = [
path("", views.index, name="index"),
]
Tu directorio de la aplicación debería ahora tener este aspecto:
polls/
__init__.py
admin.py
apps.py
migrations/
__init__.py
models.py
tests.py
urls.py
views.py
El próximo paso es configurar el URLconf raíz en el proyecto mysite para incluir el URLconf definido en polls.urls. Para hacer esto, agrega una importación para django.urls.include en mysite/urls.py y inserta un include() en la lista de urlpatterns, así que tendrás:
mysite/urls.py¶from django.contrib import admin
from django.urls import include, path
urlpatterns = [
path("polls/", include("polls.urls")),
path("admin/", admin.site.urls),
]
La función path() espera al menos dos argumentos: route y view. La función include() permite referenciar otros URLconfs. Cada vez que Django encuentra include(), corta lo que se ha encontrado en la URL hasta ese punto y envía el resto de la cadena al URLconf incluido para un procesamiento adicional.
La idea detrás de include() es hacer fácil conectar y desconectar URLs. Dado que las encuestas están en su propio URLconf (polls/urls.py), pueden estar bajo «/encuestas/», o bajo «/divertidas_encuestas/», o bajo «/contenido/encuestas/», o cualquier otro raíz de ruta, y la aplicación seguirá funcionando.
Cuando utilizar include()
Debes usar siempre include() cuando incluyas otros patrones de URL. La única excepción es admin.site.urls, que es un URLconf preconstruido proporcionado por Django para el sitio administrativo predeterminado.
Has conectado ahora una vista index al URLconf. Verifica que funciona con la siguiente orden:
$ python manage.py runserver
Ve a http://localhost:8000/polls/ en tu navegador, y deberías ver el texto «Hola, mundo. Estás en la página de inicio de encuestas.», que definiste en la vista index.
No se encuentra la página?
Si obtienes una página de error aquí, verifica que vas a http://localhost:8000/polls/ y no a http://localhost:8000/.
Cuando estés cómodo con el flujo básico de solicitud y respuesta, lee parte 2 de este tutorial para empezar a trabajar con la base de datos.
may 31, 2026