En general, los sitios web necesitan servir archivos adicionales como imágenes, JavaScript o CSS. En Django, denominamos a estos archivos «archivos estáticos». Django proporciona django.contrib.staticfiles para ayudarte a gestionarlos.
Esta página describe cómo puedes servir estos archivos estáticos.
Asegúrate de que django.contrib.staticfiles esté incluido en tu INSTALLED_APPS.
En tu archivo de configuración, define STATIC_URL, por ejemplo:
STATIC_URL = "static/"
En tus plantillas, utiliza la etiqueta de plantilla static para construir la URL para el camino relativo dado utilizando el alias staticfiles de STORAGES configurado.
{% load static %}
<img src="{% static 'my_app/example.jpg' %}" alt="My image">
Almacena tus archivos estáticos en una carpeta llamada static en tu aplicación. Por ejemplo my_app/static/my_app/example.jpg.
Servir los archivos
Además de estos pasos de configuración, también necesitarás servir los archivos estáticos en realidad.
Durante el desarrollo, si utilizas django.contrib.staticfiles, esto se hará automáticamente por runserver cuando DEBUG esté configurado en True (consulte django.contrib.staticfiles.views.serve()).
Este método es grossly inefficient y probablemente inseguro, por lo que no es adecuado para producción.
Ver Cómo desplegar archivos estáticos para estrategias adecuadas para servir archivos estáticos en entornos de producción.
Tu proyecto probablemente también tendrá activos estáticos que no están ligados a una aplicación en particular. Además de utilizar un directorio static/ dentro de tus aplicaciones, puedes definir una lista de directorios (STATICFILES_DIRS) en tu archivo de configuración donde Django buscará también archivos estáticos. Por ejemplo:
STATICFILES_DIRS = [
BASE_DIR / "static",
"/var/www/static/",
]
Ver la documentación para el parámetro de configuración STATICFILES_FINDERS para obtener detalles sobre cómo staticfiles encuentra tus archivos.
Nombres de archivo de espacio de nombres estáticos
Ahora podríamos intentar sacar el tiro por la culata y poner nuestros archivos estáticos directamente en my_app/static/ (en lugar de crear otra subcarpeta my_app), pero sería una mala idea. Django utilizará el primer archivo estático que encuentre cuyo nombre coincida, y si tenías un archivo estático con el mismo nombre en otra aplicación, Django no podría distinguir entre ellos. Necesitamos poder señalar a Django la correcta, y la mejor manera de asegurarlo es nombrándolos. Es decir, poniendo esos archivos estáticos dentro de otra carpeta llamada por el nombre de la aplicación misma.
Puedes nombrar espacios de nombres para los activos estáticos en :setting:`STATICFILES_DIRS especificando :ref:`prefixes <staticfiles-dirs-prefixes>`.
Si utilizas :mod:`django.contrib.staticfiles tal como se explica anteriormente, runserver lo hará automáticamente cuando DEBUG esté configurado en True. Si no tienes django.contrib.staticfiles en INSTALLED_APPS, todavía puedes servir archivos estáticos manualmente utilizando la vista django.views.static.serve().
Esto no es adecuado para el uso de producción! Para algunas estrategias de despliegue comunes, consulte Cómo desplegar archivos estáticos.
Por ejemplo, si tu STATIC_URL está definido como static/, puedes hacer esto agregando la siguiente snippet a tu urls.py:
from django.conf import settings
from django.conf.urls.static import static
urlpatterns = [
# ... the rest of your URLconf goes here ...
] + static(settings.STATIC_URL, document_root=settings.STATIC_ROOT)
Nota
Esta función de ayuda solo funciona en modo depuración y solo si el prefijo dado es local (por ejemplo, static/) y no una URL (por ejemplo, http://static.example.com/).
También esta función de ayuda solo sirve la carpeta STATIC_ROOT real; no realiza la búsqueda de archivos estáticos como :mod:`django.contrib.staticfiles.
Finalmente, los archivos estáticos se sirven mediante un wrapper en el nivel de aplicación WSGI. Como consecuencia, las solicitudes de archivos estáticos no pasan por la cadena normal de middleware.
Durante el desarrollo, puedes servir los archivos de medios subidos por usuarios desde MEDIA_ROOT utilizando la vista django.views.static.serve().
Esto no es adecuado para el uso de producción! Para algunas estrategias de despliegue comunes, consulte Cómo desplegar archivos estáticos.
Por ejemplo, si tu MEDIA_URL está definido como media/, puedes hacer esto agregando la siguiente snippet a tu ROOT_URLCONF:
from django.conf import settings
from django.conf.urls.static import static
urlpatterns = [
# ... the rest of your URLconf goes here ...
] + static(settings.MEDIA_URL, document_root=settings.MEDIA_ROOT)
Nota
Esta función de ayuda solo funciona en modo depuración y solo si el prefijo dado es local (por ejemplo, media/) y no una URL (por ejemplo, http://media.example.com/).
When ejecutando pruebas que utilizan solicitudes HTTP reales en lugar del cliente de prueba integrado (es decir, cuando se utiliza el cliente de prueba integrado LiveServerTestCase) los activos estáticos deben servirse junto con el resto del contenido para que el entorno de prueba reproduzca el real lo más fielmente posible, pero LiveServerTestCase tiene solo una funcionalidad muy básica para servir archivos estáticos: No sabe sobre la característica de búsqueda de los finders de la aplicación staticfiles y asume que el contenido estático ya ha sido recopilado bajo STATIC_ROOT.
Por esta razón, staticfiles envía su propio django.contrib.staticfiles.testing.StaticLiveServerTestCase, una subclase de la integrada que tiene la capacidad de servir transparentemente todos los activos durante la ejecución de estas pruebas de manera muy similar a lo que obtenemos en tiempo de desarrollo con DEBUG = True, es decir, sin tener que recopilarlos utilizando collectstatic primero.
django.contrib.staticfiles proporciona un comando administrativo conveniente para recopilar archivos estáticos en un directorio único para poder servirlos fácilmente.
Establece la configuración STATIC_ROOT en el directorio desde el que deseas servir estos archivos, por ejemplo:
STATIC_ROOT = "/var/www/example.com/static/"
Ejecuta el comando administrativo collectstatic:
$ python manage.py collectstatic
Esto copiará todos los archivos de tus carpetas estáticas al directorio STATIC_ROOT.
Utiliza un servidor web de tu elección para servir los archivos. Cómo desplegar archivos estáticos cubre algunas estrategias de despliegue comunes para archivos estáticos.
Este documento ha cubierto las bases y algunos patrones de uso común. Para obtener detalles completos sobre todas las configuraciones, comandos, etiquetas de plantilla y otras piezas incluidas en django.contrib.staticfiles, consulte la referencia a staticfiles.
may 31, 2026