Introduction to Django Static Files

Most web applications need files that are not generated dynamically by Python.

Examples include:

• CSS stylesheets
• JavaScript files
• logos
• icons
• background images
• fonts
• frontend libraries

Django refers to these files as static files.

Static files are different from uploaded media.

Static files are part of the application’s source code and are usually created by developers. Uploaded media is created or submitted by users while the application is running.

A simple distinction is:

1
2
3
4
5

Static files
    CSS, JavaScript, logos, icons, bundled assets

Media files
    Profile photos, uploaded documents, product images

Django provides the django.contrib.staticfiles application to locate, organize, collect, and serve static assets.

What Are Static Files?

A static file is a file that the server can return without generating its contents for each request.

For example, a stylesheet may contain:

1
2
3
4

body {
    font-family: sans-serif;
    margin: 0;
}

The file does not need to be rebuilt every time a user opens a page.

A browser requests it directly:

1

/static/css/site.css

Django templates can generate the correct URL for that file.

1
2
3
4
5
6

{% load static %}

<link
    rel="stylesheet"
    href="{% static 'css/site.css' %}"
>

Enabling Static Files

A standard Django project usually includes the static-files application by default.

Check INSTALLED_APPS in settings.py:

1
2
3
4
5
6
7
8

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

The important entry is:

1

"django.contrib.staticfiles"

The project should also define STATIC_URL:

1

STATIC_URL = "static/"

This is the URL prefix used for static assets.

For example:

1
2
3

/static/css/site.css
/static/js/app.js
/static/images/logo.svg

App-Level Static Files

Each Django app can contain its own static files.

A common app structure is:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

blog/
├── static/
│   └── blog/
│       ├── css/
│       │   └── article.css
│       ├── js/
│       │   └── article.js
│       └── images/
│           └── logo.svg
├── templates/
├── models.py
├── views.py
└── urls.py

The extra blog/ directory inside static/ is important.

The full path is:

1

blog/static/blog/css/article.css

The file is referenced as:

1

{% static 'blog/css/article.css' %}

This namespacing prevents filename collisions.

Without namespacing, two apps might both contain:

1

static/css/style.css

Django would find one of them first, and the result could depend on app order.

Using app names creates unique paths:

1
2
3

blog/css/style.css
shop/css/style.css
accounts/css/style.css

Loading Static Files in Templates

Before using the static template tag, load it:

1

{% load static %}

Then reference a file:

1
2
3
4

<link
    rel="stylesheet"
    href="{% static 'blog/css/article.css' %}"
>

JavaScript:

1
2
3
4

<script
    src="{% static 'blog/js/article.js' %}"
    defer
></script>

Image:

1
2
3
4

<img
    src="{% static 'blog/images/logo.svg' %}"
    alt="Blog logo"
>

The static tag builds the URL using the project’s static-file configuration.

Avoid hard-coding URLs like this:

1

<link rel="stylesheet" href="/static/blog/css/article.css">

The hard-coded path may work locally, but the final URL may differ in production.

Prefer:

1
2
3
4
5
6

{% load static %}

<link
    rel="stylesheet"
    href="{% static 'blog/css/article.css' %}"
>

Project-Level Static Files

Some static assets belong to the entire project rather than one app.

Examples include:

• the main site stylesheet
• shared JavaScript
• a company logo
• global icons
• a design system

A project-level static directory might look like:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

project/
├── manage.py
├── config/
├── static/
│   ├── css/
│   │   └── site.css
│   ├── js/
│   │   └── site.js
│   └── images/
│       └── logo.svg
└── templates/

Tell Django to search this directory with STATICFILES_DIRS:

1
2
3

STATICFILES_DIRS = [
    BASE_DIR / "static",
]

The files can then be referenced as:

1
2
3
4
5
6

{% load static %}

<link
    rel="stylesheet"
    href="{% static 'css/site.css' %}"
>

App-Level and Project-Level Static Files

A project may use both approaches.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

project/
├── static/
│   └── css/
│       └── site.css
├── blog/
│   └── static/
│       └── blog/
│           └── css/
│               └── article.css
└── shop/
    └── static/
        └── shop/
            └── css/
                └── product.css

Use project-level static files for assets shared across the entire site.

Use app-level static files for assets owned by one reusable or isolated app.

STATIC_URL

STATIC_URL defines the public URL prefix for static files.

1

STATIC_URL = "static/"

This usually produces URLs such as:

1

/static/css/site.css

It can also be written with a leading slash:

1

STATIC_URL = "/static/"

In production, it may point to a separate static-file host:

1

STATIC_URL = "https://static.example.com/"

Templates should continue using the static tag, so they do not need to know the final deployment URL.

STATICFILES_DIRS

STATICFILES_DIRS lists additional directories Django should search for static assets.

Example:

1
2
3

STATICFILES_DIRS = [
    BASE_DIR / "static",
]

Multiple directories may be included:

1
2
3
4

STATICFILES_DIRS = [
    BASE_DIR / "static",
    BASE_DIR / "frontend" / "dist" / "assets",
]

These directories are separate from the app-level static directories that Django discovers automatically.

STATIC_ROOT

STATIC_ROOT is the directory where Django collects static files for production.

Example:

1

STATIC_ROOT = BASE_DIR / "staticfiles"

This directory is normally populated by:

1

python manage.py collectstatic

A typical configuration is:

1
2
3
4
5
6
7

STATIC_URL = "static/"

STATICFILES_DIRS = [
    BASE_DIR / "static",
]

STATIC_ROOT = BASE_DIR / "staticfiles"

These settings have different purposes:

Do not normally use the same directory for both STATICFILES_DIRS and STATIC_ROOT.

Incorrect:

1
2
3
4
5

STATICFILES_DIRS = [
    BASE_DIR / "staticfiles",
]

STATIC_ROOT = BASE_DIR / "staticfiles"

This mixes source assets with collected output.

Prefer:

1
2
3
4
5

STATICFILES_DIRS = [
    BASE_DIR / "static",
]

STATIC_ROOT = BASE_DIR / "staticfiles"

Static Files During Development

When DEBUG=True, Django’s development server can serve static files automatically if django.contrib.staticfiles is installed.

Run:

1

python manage.py runserver

A file referenced as:

1

{% static 'css/site.css' %}

may be available at:

1

http://127.0.0.1:8000/static/css/site.css

This behavior is intended for development.

Django’s development server is not designed to be a high-performance production static-file server.

The collectstatic Command

Production deployments usually gather all static assets into one directory.

Run:

1

python manage.py collectstatic

Django searches:

• app-level static directories
• directories listed in STATICFILES_DIRS
• other configured static-file sources

It copies the discovered files into STATIC_ROOT.

For example:

1
2
3
4
5

Source files:

blog/static/blog/css/article.css
shop/static/shop/css/product.css
static/css/site.css

After collectstatic:

1
2
3
4
5
6
7
8
9

staticfiles/
├── blog/
│   └── css/
│       └── article.css
├── shop/
│   └── css/
│       └── product.css
└── css/
    └── site.css

A production web server or storage service can then serve the staticfiles directory.

Why collectstatic Exists

Django projects may contain static assets in many locations.

Without collection, a production server would need to understand the internal directory structure of every installed app.

collectstatic creates one deployment directory containing all required assets.

The deployment flow becomes:

1
2
3
4
5
6
7
8
9

App static directories
Project static directories
Third-party package assets
        ↓
collectstatic
        ↓
STATIC_ROOT
        ↓
Web server or static storage

Running collectstatic

A common production command is:

1

python manage.py collectstatic --noinput

--noinput prevents interactive confirmation prompts.

This is useful in automated deployment pipelines.

When the command runs again, Django may overwrite changed files and leave unchanged files in place.

Finding Static Files

Django provides the findstatic command to locate a file.

1

python manage.py findstatic css/site.css

For an app-namespaced file:

1

python manage.py findstatic blog/css/article.css

Verbose output can show all searched locations:

1

python manage.py findstatic blog/css/article.css --verbosity 2

This command is useful when:

• Django cannot find an asset
• the wrong file is being used
• two files have the same path
• a project directory is misconfigured

Static File Finders

Django uses static-file finders to locate assets.

The default configuration typically includes:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

STATICFILES_FINDERS = [
    (
        "django.contrib.staticfiles.finders."
        "FileSystemFinder"
    ),
    (
        "django.contrib.staticfiles.finders."
        "AppDirectoriesFinder"
    ),
]

FileSystemFinder searches directories in STATICFILES_DIRS.

AppDirectoriesFinder searches static directories inside installed apps.

Most projects do not need to change this setting.

File Name Collisions

Django uses the first static file it finds for a particular path.

Suppose two apps contain:

1
2

blog/static/css/style.css
shop/static/css/style.css

Both use the same static path:

1

css/style.css

One file will hide the other.

Avoid this by adding an app namespace:

1
2

blog/static/blog/css/style.css
shop/static/shop/css/style.css

Then reference them separately:

1

{% static 'blog/css/style.css' %}

1

{% static 'shop/css/style.css' %}

Static Images in CSS

A CSS file may reference another static asset.

Suppose the structure is:

1
2
3
4
5

static/
├── css/
│   └── site.css
└── images/
    └── background.png

Inside site.css:

1
2
3

.hero {
    background-image: url("../images/background.png");
}

The path is relative to the CSS file.

Django template tags do not run inside ordinary CSS files.

This will not work inside site.css:

1
2
3
4

.hero {
    background-image:
        url("{% static 'images/background.png' %}");
}

Template tags are processed only in Django templates.

Use relative paths in static CSS files, or generate inline CSS in a Django template when necessary.

Adding CSS to a Base Template

A common base template is:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33

{% load static %}

<!doctype html>
<html lang="en">
<head>
    <meta charset="utf-8">
    <meta
        name="viewport"
        content="width=device-width, initial-scale=1"
    >

    <title>
        {% block title %}My Site{% endblock %}
    </title>

    <link
        rel="stylesheet"
        href="{% static 'css/site.css' %}"
    >

    {% block extra_css %}{% endblock %}
</head>
<body>
    {% block content %}{% endblock %}

    <script
        src="{% static 'js/site.js' %}"
        defer
    ></script>

    {% block extra_js %}{% endblock %}
</body>
</html>

A child template can add app-specific assets:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

{% extends "base.html" %}
{% load static %}

{% block title %}Articles{% endblock %}

{% block extra_css %}
    <link
        rel="stylesheet"
        href="{% static 'blog/css/article.css' %}"
    >
{% endblock %}

{% block content %}
    <h1>Articles</h1>
{% endblock %}

Static JavaScript Files

A JavaScript file can be added in the same way as a stylesheet.

Project structure:

1
2
3

static/
└── js/
    └── site.js

Template:

1
2
3
4
5
6

{% load static %}

<script
    src="{% static 'js/site.js' %}"
    defer
></script>

Using defer tells the browser to download the script without blocking HTML parsing and execute it after the document has been parsed.

A JavaScript file might contain:

1
2
3

document.addEventListener("DOMContentLoaded", () => {
    console.log("Site JavaScript loaded.");
});

Static Files and the Django Admin

The Django admin uses static assets for its CSS, JavaScript, and images.

These assets come from django.contrib.admin.

During collectstatic, Django also collects the admin’s static files.

A production deployment where the admin appears unstyled often has one of these problems:

• collectstatic was not run
• STATIC_ROOT is not served
• the static URL is misconfigured
• the web server cannot access the collected files

Static Files and Uploaded Media

Static files and media files should use separate settings.

Example:

1
2
3
4
5

STATIC_URL = "static/"
STATIC_ROOT = BASE_DIR / "staticfiles"

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

Static example:

1

/static/css/site.css

Media example:

1

/media/profile-images/user-42.jpg

A model upload uses media storage:

1
2
3
4

class Profile(models.Model):
    image = models.ImageField(
        upload_to="profile-images/",
    )

The uploaded image does not belong in the static directory.

Serving Media During Development

Static files are normally handled automatically by django.contrib.staticfiles during development.

Uploaded media often needs an additional development URL pattern:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

from django.conf import settings
from django.conf.urls.static import static
from django.contrib import admin
from django.urls import path


urlpatterns = [
    path("admin/", admin.site.urls),
]

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

This helper is for development only.

It should not be treated as a production media-serving solution.

Production Static-File Serving

In production, static files are commonly served by:

• Nginx
• Apache
• a cloud object-storage service
• a content delivery network
• a platform-specific static-file service
• a package such as WhiteNoise

Django usually handles dynamic requests, while a specialized server handles static files.

1
2
3
4

Browser
   ├── /static/... → static-file server
   ├── /media/...  → media storage
   └── /articles/  → Django application

This is more efficient than sending every CSS, JavaScript, and image request through Django.

Serving Static Files with Nginx

A conceptual Nginx configuration might look like:

1
2
3

location /static/ {
    alias /srv/app/staticfiles/;
}

The path should point to STATIC_ROOT.

Django settings:

1
2

STATIC_URL = "/static/"
STATIC_ROOT = BASE_DIR / "staticfiles"

Deployment command:

1

python manage.py collectstatic --noinput

Nginx then serves files directly from the collected directory.

WhiteNoise

WhiteNoise allows a Django application to serve its own static assets in production.

Install it:

1

python -m pip install whitenoise

Add its middleware near the top of the middleware list:

1
2
3
4
5

MIDDLEWARE = [
    "django.middleware.security.SecurityMiddleware",
    "whitenoise.middleware.WhiteNoiseMiddleware",
    # ...
]

A simple static configuration might include:

1
2

STATIC_URL = "static/"
STATIC_ROOT = BASE_DIR / "staticfiles"

WhiteNoise is useful for deployments where using a separate Nginx server or object-storage service would add unnecessary complexity.

It is especially common on application-hosting platforms.

Hashed Static File Names

Browsers cache static files.

This improves performance, but it creates a problem when a file changes.

Suppose the browser caches:

1

/static/css/site.css

You deploy a new version with the same URL. The browser may continue using the old cached file.

Hashed filenames solve this problem:

1

site.4f63a19c.css

When the file changes, the hash changes:

1

site.91b725d8.css

The browser sees a new URL and downloads the new file.

A production storage backend can provide this behavior through Django’s static-file storage configuration.

For example, WhiteNoise commonly uses compressed manifest storage.

The exact setting depends on the Django version and storage configuration, but the goal is the same:

• add content hashes to filenames
• compress assets
• support long browser-cache lifetimes

Static Files and Frontend Build Tools

Modern projects may use tools such as:

• Vite
• Webpack
• Sass
• Tailwind CSS
• TypeScript
• React
• Vue

These tools produce compiled assets.

For example:

1
2
3
4
5
6
7

Frontend source
    ↓ npm run build
Compiled CSS and JavaScript
    ↓
Django static source directory
    ↓ collectstatic
STATIC_ROOT

A Vite build might produce:

1
2
3
4
5

frontend/dist/
├── assets/
│   ├── index-abc123.js
│   └── index-def456.css
└── index.html

Django can be configured to collect these compiled assets by adding the generated directory to STATICFILES_DIRS:

1
2
3

STATICFILES_DIRS = [
    BASE_DIR / "frontend" / "dist" / "assets",
]

However, build tools often generate hashed filenames and manifests. A reliable integration may require:

• reading the frontend build manifest
• using a Django integration package
• copying generated assets into a known structure
• serving the frontend separately

Do not hard-code generated filenames that may change on every build.

Organizing Static Files

A simple project-wide layout is:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

static/
├── css/
│   ├── reset.css
│   ├── site.css
│   └── components.css
├── js/
│   ├── site.js
│   └── forms.js
├── images/
│   ├── logo.svg
│   └── hero.jpg
└── fonts/
    └── example.woff2

A larger project may group assets by feature:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

static/
├── core/
│   ├── css/
│   └── js/
├── accounts/
│   ├── css/
│   └── js/
└── shop/
    ├── css/
    ├── js/
    └── images/

The best structure depends on the application.

The important points are:

• keep paths predictable
• avoid filename collisions
• separate source assets from collected output
• use app namespaces for reusable apps

Common Beginner Mistakes

Forgetting {% load static %}

Incorrect:

1
2
3
4

<link
    rel="stylesheet"
    href="{% static 'css/site.css' %}"
>

Correct:

1
2
3
4
5
6

{% load static %}

<link
    rel="stylesheet"
    href="{% static 'css/site.css' %}"
>

Hard-Coding Static URLs

Avoid:

1

<img src="/static/images/logo.svg" alt="Logo">

Prefer:

1
2
3
4
5
6

{% load static %}

<img
    src="{% static 'images/logo.svg' %}"
    alt="Logo"
>

Using the Wrong Static Path

Given:

1

blog/static/blog/css/article.css

Use:

1

{% static 'blog/css/article.css' %}

Do not use:

1

{% static 'static/blog/css/article.css' %}

The static/ directory itself is not part of the referenced path.

Forgetting App Namespacing

Avoid:

1
2

blog/static/css/style.css
shop/static/css/style.css

Prefer:

1
2

blog/static/blog/css/style.css
shop/static/shop/css/style.css

Putting Uploaded Files in static/

User uploads belong in MEDIA_ROOT, not in static source directories.

Using STATIC_ROOT as a Source Directory

STATIC_ROOT is collected output.

Do not manually develop files there because collectstatic may overwrite them.

Forgetting collectstatic in Production

If the application works locally but has no CSS in production, verify that this command ran:

1

python manage.py collectstatic --noinput

Expecting Django to Serve Static Files in Production Automatically

The development server’s static-file behavior does not represent a complete production setup.

Configure a production static-file server, storage service, or suitable middleware.

Confusing STATICFILES_DIRS and STATIC_ROOT

Remember:

1
2
3
4
5

STATICFILES_DIRS
    Input directories

STATIC_ROOT
    Collected output directory

Writing Template Tags Inside CSS

This does not work in an ordinary static CSS file:

1
2

background-image:
    url("{% static 'images/background.png' %}");

Use a relative path or inline template-generated CSS.

Debugging Static Files

When an asset does not load, first inspect the browser’s network panel.

Check:

• the requested URL
• the response status
• whether the response is CSS, JavaScript, HTML, or an error page
• whether the file is cached

Then check Django’s file discovery:

1

python manage.py findstatic css/site.css

Review the settings:

1
2
3
4
5
6
7

STATIC_URL = "static/"

STATICFILES_DIRS = [
    BASE_DIR / "static",
]

STATIC_ROOT = BASE_DIR / "staticfiles"

Check the actual source file:

1

project/static/css/site.css

Check the template reference:

1
2
3
4
5
6

{% load static %}

<link
    rel="stylesheet"
    href="{% static 'css/site.css' %}"
>

For production, confirm that the collected file exists:

1

staticfiles/css/site.css

A Complete Basic Setup

Project structure:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

project/
├── manage.py
├── config/
│   └── settings.py
├── static/
│   ├── css/
│   │   └── site.css
│   ├── js/
│   │   └── site.js
│   └── images/
│       └── logo.svg
├── staticfiles/
└── templates/
    └── base.html

Settings:

1
2
3
4
5
6
7

STATIC_URL = "static/"

STATICFILES_DIRS = [
    BASE_DIR / "static",
]

STATIC_ROOT = BASE_DIR / "staticfiles"

Template:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36

{% load static %}

<!doctype html>
<html lang="en">
<head>
    <meta charset="utf-8">
    <meta
        name="viewport"
        content="width=device-width, initial-scale=1"
    >

    <title>Example Site</title>

    <link
        rel="stylesheet"
        href="{% static 'css/site.css' %}"
    >
</head>
<body>
    <header>
        <img
            src="{% static 'images/logo.svg' %}"
            alt="Example Site"
        >
    </header>

    <main>
        <h1>Django Static Files</h1>
    </main>

    <script
        src="{% static 'js/site.js' %}"
        defer
    ></script>
</body>
</html>

Development:

1

python manage.py runserver

Production collection:

1

python manage.py collectstatic --noinput

Recommended Workflow

During development:

1. Add app-specific assets to the app’s namespaced static directory.
2. Add shared assets to a project-level static directory.
3. Reference assets with {% static %}.
4. Test with the development server.
5. Use findstatic when a file cannot be located.

During deployment:

1. Build frontend assets if a build tool is used.
2. Run collectstatic.
3. Serve STATIC_ROOT through a production static-file system.
4. Verify CSS, JavaScript, images, and admin assets.
5. Configure caching and hashed filenames when appropriate.

Mini Reference

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20

STATIC_URL
    Public URL prefix for static assets

STATICFILES_DIRS
    Additional source directories

STATIC_ROOT
    Production collection directory

{% load static %}
    Loads the static template tag

{% static "path/file.css" %}
    Creates the static asset URL

collectstatic
    Copies discovered assets into STATIC_ROOT

findstatic
    Shows where Django finds an asset

Basic settings:

1
2
3
4
5
6
7

STATIC_URL = "static/"

STATICFILES_DIRS = [
    BASE_DIR / "static",
]

STATIC_ROOT = BASE_DIR / "staticfiles"

Basic template usage:

1
2
3
4
5
6

{% load static %}

<link
    rel="stylesheet"
    href="{% static 'css/site.css' %}"
>

App-level asset:

1

blog/static/blog/css/article.css

Template path:

1

{% static 'blog/css/article.css' %}

Production command:

1

python manage.py collectstatic --noinput

Django static files are the CSS, JavaScript, images, fonts, and other developer-controlled assets used by an application.

The main ideas are:

• django.contrib.staticfiles manages static assets
• app-level files belong inside app static directories
• reusable apps should namespace their static paths
• project-wide assets can be listed through STATICFILES_DIRS
• templates should use the {% static %} tag
• STATIC_URL defines the public asset prefix
• STATIC_ROOT stores collected production files
• collectstatic prepares assets for deployment
• static files and uploaded media are separate concepts
• production assets should be served by an appropriate static-file system

For a small project, begin with one project-level static directory and the static template tag. Add app-level namespacing, asset compilation, hashed filenames, and external storage only when the project requires them.