# How to Load Static in Django: Avoiding Common Pitfalls and Configuration Errors > Learn to load static in Django effectively. Avoid common pitfalls with template tags, INSTALLED_APPS, and collectstatic for seamless asset serving. - Repository: [Django/django](https://github.com/django/django) - Tags: how-to-guide - Published: 2026-02-16 --- **To load static in Django correctly, you must use the `{% static %}` template tag after loading the static library, ensure `django.contrib.staticfiles` is in `INSTALLED_APPS`, and run `collectstatic` before deploying with `DEBUG=False`.** Working with Django templates requires precise configuration to serve CSS, JavaScript, and images properly. When you load static in Django, the framework relies on specific template tags, settings, and storage backends defined in the `django/django` repository. Misconfigurations in any layer—template syntax, project settings, or deployment strategy—result in 404 errors, broken cache-busting, or security vulnerabilities. ## Template-Side Mistakes When You Load Static in Django ### Forgetting the Load Statement The `{% static %}` tag is not a built-in global. In [`django/templatetags/static.py`](https://github.com/django/django/blob/main/django/templatetags/static.py), the tag is registered only when the library is loaded. If you omit `{% load static %}` at the top of your template, Django renders the literal text `{% static "css/base.css" %}` instead of the URL. ```django {% load static %} ``` ### Using Deprecated Tag Names Prior to Django 1.10, the tag was named `{% staticfiles %}`. Attempting to use this legacy name now raises a `TemplateSyntaxError`. Always use the current `{% static %}` tag. ### Passing Absolute Paths or Full URLs The `static` template tag expects a **relative** path from your static files directory. Providing a leading slash (e.g., [`/css/base.css`](https://github.com/django/django/blob/main//css/base.css)) causes Django to double-prefix `STATIC_URL`, resulting in malformed URLs like [`/static//css/base.css`](https://github.com/django/django/blob/main//static//css/base.css). ```django {# Correct #} Logo {# Incorrect - do not use leading slashes #} Logo ``` ### Syntax Errors with Variables When passing a literal string, you must use quotes. Without quotes, Django interprets the value as a template variable and raises "Could not parse the remainder". When using a context variable, pass it directly without curly braces. ```django {# Literal string - requires quotes #} {# Context variable - no quotes or braces #} {% static image_path %} ``` ### Hardcoding STATIC_URL in Templates Manually writing `{{ STATIC_URL }}css/base.css` bypasses the storage backend. This disables cache-busting features provided by `ManifestStaticFilesStorage` (implemented in [`django/contrib/staticfiles/storage.py`](https://github.com/django/django/blob/main/django/contrib/staticfiles/storage.py) lines 37-48) and prevents Django from handling hashed filenames. ## Project Configuration Pitfalls for Django Static Files ### Missing staticfiles in INSTALLED_APPS If `django.contrib.staticfiles` is absent from `INSTALLED_APPS`, the `{% static %}` tag falls back to a simple URL join operation. This ignores custom finders and storage backends, breaking advanced features like hashed asset names. ```python INSTALLED_APPS = [ # ... other apps ... "django.contrib.staticfiles", ] ``` ### Undefined STATIC_URL Without `STATIC_URL`, the `static` template tag returns an empty string. Assets fail to load entirely. ```python STATIC_URL = "/static/" ``` ### Missing STATIC_ROOT in Production `STATIC_ROOT` defines the directory where `collectstatic` gathers files for deployment. If unset, the management command raises an error. ```python STATIC_ROOT = BASE_DIR / "staticfiles" ``` ### Running DEBUG=False Without Collecting Static When `DEBUG=False`, Django does not serve static files automatically. If you have not run `python manage.py collectstatic`, requests for CSS or JavaScript return 404 errors. ### Misconfigured STORAGES Dictionary Django 4.2+ uses the `STORAGES` setting to define storage backends. If you configure a custom storage for static files (e.g., `ManifestStaticFilesStorage`) but fail to update `STORAGES["staticfiles"]`, the `static` tag continues using the default filesystem storage. ```python STORAGES = { "staticfiles": { "BACKEND": "django.contrib.staticfiles.storage.ManifestStaticFilesStorage", }, } ``` ### Incorrect STATICFILES_DIRS This setting lists additional directories beyond app `static/` folders. If paths are incorrect or omitted, `collectstatic` cannot find your assets. ```python STATICFILES_DIRS = [ BASE_DIR / "assets", BASE_DIR / "frontend" / "dist", ] ``` ## Deployment and Serving Mistakes ### Using Django's Development View in Production The `django.contrib.staticfiles.views.serve` view is documented as "grossly inefficient" and insecure. Never use Django to serve static files in production. Use nginx, Apache, or a CDN instead. ### Missing staticfiles_urlpatterns in Custom URLs If you override [`urls.py`](https://github.com/django/django/blob/main/urls.py) and forget to include static file URLs during development, `runserver` cannot serve assets. ```python from django.contrib.staticfiles.urls import staticfiles_urlpatterns urlpatterns = [ # ... your patterns ... ] if settings.DEBUG: urlpatterns += staticfiles_urlpatterns() ``` ### Misusing --insecure Flag The `--insecure` flag forces `runserver` to serve static files even when `DEBUG=False`. This uses the inefficient development view and poses security risks. Use it only for local debugging, never in production. ### Broken Cache-Busting When using `ManifestStaticFilesStorage`, failing to run `collectstatic` after changing assets leaves old hashed filenames in the manifest. Browsers cache stale files. ### Incorrect MIME Types If your web server lacks MIME type definitions, browsers may refuse to render CSS or execute JavaScript. Install `mailcap` on Debian/Ubuntu or `mime-support` on Red Hat systems. ## Correct Implementation Examples ### Minimal Template Syntax Always load the library at the top of the template. Use quoted relative paths for literals and unquoted variables for dynamic paths. ```django {% load static %} My Site Logo ``` ### Production-Ready Settings Configure `STORAGES` to use `ManifestStaticFilesStorage` for automatic cache-busting via hashed filenames. ```python # settings.py INSTALLED_APPS = [ # ... "django.contrib.staticfiles", ] STATIC_URL = "/static/" STATIC_ROOT = BASE_DIR / "staticfiles" STATICFILES_DIRS = [BASE_DIR / "assets"] STORAGES = { "staticfiles": { "BACKEND": "django.contrib.staticfiles.storage.ManifestStaticFilesStorage", }, } ``` ### Management Commands Run `collectstatic` after every deployment to gather files into `STATIC_ROOT`. ```bash # Collect static files (production) python manage.py collectstatic --noinput # Development server with DEBUG=False (use --insecure only locally) python manage.py runserver --insecure ``` ### Python Code and Email Templates When rendering static URLs outside of templates (e.g., in email generation or management commands), use the storage backend directly rather than hardcoding paths. ```python from django.templatetags.static import static # Returns the properly hashed URL if using ManifestStaticFilesStorage logo_url = static("images/logo.png") # Alternative: direct storage access from django.core.files.storage import staticfiles_storage logo_url = staticfiles_storage.url("images/logo.png") ``` ## Key Source Files in Django Understanding the implementation helps debug issues when you load static in Django: - **[`django/templatetags/static.py`](https://github.com/django/django/blob/main/django/templatetags/static.py)** (lines 55-71): Implements the `{% static %}` tag and `StaticNode` class, which resolves paths using `staticfiles_storage`. - **[`django/contrib/staticfiles/storage.py`](https://github.com/django/django/blob/main/django/contrib/staticfiles/storage.py)** (lines 37-48): Contains `ManifestStaticFilesStorage`, which generates hashed filenames for cache-busting and maintains the [`staticfiles.json`](https://github.com/django/django/blob/main/staticfiles.json) manifest. - **[`django/contrib/staticfiles/urls.py`](https://github.com/django/django/blob/main/django/contrib/staticfiles/urls.py)**: Defines `staticfiles_urlpatterns()` for development serving. - **[`django/contrib/staticfiles/views.py`](https://github.com/django/django/blob/main/django/contrib/staticfiles/views.py)**: Houses the `serve` view used during development (inefficient for production). ## Summary - **Always include `{% load static %}`** at the top of templates before using the `static` tag. - **Use relative paths** without leading slashes inside `{% static %}` tags. - **Configure `INSTALLED_APPS`**, `STATIC_URL`, and `STATIC_ROOT` correctly for both development and production. - **Run `collectstatic`** after every deployment when `DEBUG=False`. - **Use `ManifestStaticFilesStorage`** for automatic cache-busting via hashed filenames. - **Never serve static files with Django in production**; use nginx, Apache, or a CDN. ## Frequently Asked Questions ### Why do I get a TemplateSyntaxError when trying to load static in Django? A `TemplateSyntaxError` usually occurs because you forgot to add `{% load static %}` at the top of your template, or you are using the deprecated `{% staticfiles %}` tag from Django versions prior to 1.10. Always use `{% load static %}` followed by `{% static "path/to/file.css" %}`. ### What is the difference between STATIC_URL and STATIC_ROOT? `STATIC_URL` defines the URL prefix used in templates and browsers to reference static files (e.g., `/static/`). `STATIC_ROOT` is the absolute filesystem path where `collectstatic` gathers all static files for production deployment (e.g., `/var/www/staticfiles/`). You need both: `STATIC_URL` for addressing, `STATIC_ROOT` for collection. ### Why are my static files returning 404 errors in production? Static files 404 in production typically occur because you have not run `python manage.py collectstatic` to populate `STATIC_ROOT`, or your web server (nginx, Apache) is not configured to serve files from that directory. When `DEBUG=False`, Django does not serve static files automatically; you must use a real web server or CDN. ### How do I use cache-busting with hashed filenames? Enable `ManifestStaticFilesStorage` in your `STORAGES` setting, then run `collectstatic`. This backend generates MD5-hashed filenames (e.g., [`css/base.a1b2c3d4.css`](https://github.com/django/django/blob/main/css/base.a1b2c3d4.css)) and creates a [`staticfiles.json`](https://github.com/django/django/blob/main/staticfiles.json) manifest. The `{% static %}` tag automatically reads this manifest to return the hashed URL, ensuring browsers load fresh assets after deployments.