Skip to content
Kuza Ndoto Academy

Static Files

IntermediateChapter 3 · Page 11 of 234 min readUpdated 15 Nov 2026

Static files are the files your site serves exactly as they are: CSS stylesheets, JavaScript and images such as your logo. Django's staticfiles app helps you organise them during development and gather them into one place when you go live.

Static files vs. media files

Static filesMedia files
Who creates them?You, the developerYour users (uploads)
Examplesstyle.css, logo.png, menu.jsEvent posters, profile photos
SettingsSTATIC_URL, STATIC_ROOT, STATICFILES_DIRSMEDIA_URL, MEDIA_ROOT

This page focuses on static files, with a short section on media at the end.

Step 1: Check the settings

A new project already includes "django.contrib.staticfiles" in INSTALLED_APPS and this setting:

campus/settings.py

STATIC_URL = "static/"

STATIC_URL is the URL prefix for static files, so a stylesheet will be served at an address like /static/events/css/style.css.

Step 2: Add files to your app

Like templates, static files go in a folder named after the app, inside a static/ folder in the app:

events/
└── static/
    └── events/
        ├── css/
        │   └── style.css
        └── img/
            └── logo.png

events/static/events/css/style.css

body {
    font-family: system-ui, sans-serif;
    margin: 0 auto;
    max-width: 960px;
    padding: 0 16px;
}

.event-card {
    border: 1px solid #ddd;
    border-radius: 8px;
    padding: 12px 16px;
    margin-bottom: 12px;
}

Load the static template library, then use the {% static %} tag to build each file's URL. Putting this in your base template applies the styles to every page:

templates/base.html

{% load static %}
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>{% block title %}Campus Events{% endblock %}</title>
  <link rel="stylesheet" href="{% static 'events/css/style.css' %}">
</head>
<body>
  <img src="{% static 'events/img/logo.png' %}" alt="Campus Events logo" width="120">
  {% block content %}{% endblock %}
</body>
</html>

In development, the link tag is rendered as:

<link rel="stylesheet" href="/static/events/css/style.css">

While DEBUG = True, runserver serves these files for you automatically. If you've just created a new static folder, restart the server once so it notices.

Common mistake

Forgetting {% load static %}. Django raises TemplateSyntaxError: Invalid block tag ... 'static'. Did you forget to register or load this tag? The load tag is needed in every template that uses {% static %}, including child templates: loading it in base.html does not carry over.

Common mistake

Hard-coding paths like href="/static/events/css/style.css". It works on your laptop but breaks when you change STATIC_URL, serve files from a CDN or use hashed file names in production. Always use {% static %}.

Project-wide static files

Files that don't belong to any one app, such as a site-wide logo, can live in a project-level static/ folder. Tell Django about it with STATICFILES_DIRS:

campus/settings.py

STATICFILES_DIRS = [
    BASE_DIR / "static",
]

Going live: STATIC_ROOT and collectstatic

In production, Django itself should not serve static files one by one. Instead you copy every static file from every app (including the admin's own CSS) into one folder, and a fast server or library serves that folder. Set the destination with STATIC_ROOT:

campus/settings.py

STATIC_ROOT = BASE_DIR / "staticfiles"

Then run:

python manage.py collectstatic
127 static files copied to '/home/amina/campus-events/staticfiles'.

Your count and path will differ; most of the files come from the admin app. Run collectstatic again every time you deploy changes to your CSS or JavaScript.

events/static/events/ accounts/static/accounts/ static/ (STATICFILES_DIRS) admin app's CSS and JS collectstatic staticfiles/ (STATIC_ROOT) served at /static/ in production
Figure 1. In development, Django finds files in their source folders. For production, collectstatic gathers copies into one folder that a server or WhiteNoise can serve quickly.
Warning

STATIC_ROOT must be a different folder from any folder in STATICFILES_DIRS, otherwise Django raises ImproperlyConfigured. Don't put your own files in staticfiles/ either: it's an output folder that collectstatic fills, and it should be listed in .gitignore.

Storage backends and cache busting

Browsers cache CSS files. After you change style.css, some visitors may keep seeing the old version. Django's ManifestStaticFilesStorage solves this by adding a content hash to each file name during collectstatic, e.g. style.3f8a91c2b4de.css, and {% static %} automatically points to the latest name. You configure it with the STORAGES setting:

campus/settings.py

STORAGES = {
    "default": {
        "BACKEND": "django.core.files.storage.FileSystemStorage",
    },
    "staticfiles": {
        "BACKEND": "django.contrib.staticfiles.storage.ManifestStaticFilesStorage",
    },
}

When you set STORAGES, include both keys: "default" handles uploaded media and "staticfiles" handles static files. The manifest storage only takes effect when DEBUG is False and after collectstatic has run. On the Deploying Django page you'll swap in WhiteNoise's storage class, which also compresses files and lets your app serve them efficiently.

A quick look at media files

For user uploads, such as a poster image on each event, add these settings:

campus/settings.py

MEDIA_URL = "media/"
MEDIA_ROOT = BASE_DIR / "media"

An ImageField on a model needs the Pillow library (python -m pip install pillow). In development, serve uploads by adding this to the end of the project URLconf:

campus/urls.py

from django.conf import settings
from django.conf.urls.static import static

urlpatterns += static(settings.MEDIA_URL, document_root=settings.MEDIA_ROOT)

This helper only works while DEBUG is True. In production, uploads are usually served by the web server or a cloud storage service.

Key points

  • Put app static files in app/static/app/ and shared ones in a folder listed in STATICFILES_DIRS.
  • Use {% load static %} and {% static 'path' %} in templates, never hard-coded paths.
  • collectstatic copies everything into STATIC_ROOT for production.
  • Configure static storage, including cache-busting hashed names, with the STORAGES setting.
Up next · New chapter: Models & DatabasesModelsDescribe your data in Python.
→

Tip: use the ← and → keys to move between pages.