0. Introduction

Websites are not made of HTML alone. To create attractive and interactive pages, you also need CSS, JavaScript, and images. In Django, these files are called static files.

In this tutorial, you will learn what static files are, why they are important, how Django handles them, how to configure them correctly, and how to use CSS, JavaScript, and images in your templates.

1. What Are Static Files?

Static files are files that do not change dynamically for each request. They are usually served as they are.

Common examples of static files are:

  • CSS files
  • JavaScript files
  • images
  • icons
  • fonts

Example

A stylesheet like:

body {
    background-color: #f5f5f5;
}

is a static file because Django does not generate it each time from database logic. It is simply loaded and sent to the browser.

2. Why Static Files Matter

Static files are essential because they improve both the appearance and the functionality of your website.

CSS

Used for styling:

  • colors
  • spacing
  • fonts
  • layouts
  • buttons
  • responsiveness

JavaScript

Used for interactivity:

  • dropdowns
  • modals
  • form validation
  • dynamic updates
  • animations

Images

Used for visual content:

  • logos
  • banners
  • icons
  • product photos
  • user interface elements

Without static files, your Django site would look very plain and limited.

3. Static Files vs Media Files

Beginners often confuse these two concepts.

Static files

These are files used by the website itself.

Examples:

  • site CSS
  • JavaScript
  • logo
  • icons

Media files

These are files uploaded by users or administrators.

Examples:

  • profile pictures
  • blog post images
  • product uploads
  • PDF documents uploaded by users

Important difference

  • Static files belong to the project design and frontend
  • Media files belong to user-generated or database-related content

In this tutorial, we focus only on static files.

4. Django Static Files Concept

Django provides a built-in system for handling static files during development.

To use static files correctly, Django needs:

  • a STATIC_URL
  • one or more static folders
  • the {% load static %} template tag

These work together so templates can find and display CSS, JavaScript, and images.

5. Default Static Configuration

Open your settings.py file and check for this line:

STATIC_URL = 'static/'

What does this mean?

This tells Django that static files will be accessed through URLs starting with:

/static/

For example:

/static/css/style.css

This is the public URL path, not necessarily the actual folder path.

6. Creating a Static Folder

A common way to organize static files inside an app is like this:

blog/
├── static/
│   └── blog/
│       ├── css/
│       │   └── style.css
│       ├── js/
│       │   └── script.js
│       └── images/
│           └── logo.png

Why use blog/ inside static/?

Because different apps may have files with the same name.

For example:

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

This avoids name conflicts.

7. Creating Your First CSS File

Let us create a CSS file:

blog/static/blog/css/style.css

Example content:

body {
    background-color: #f0f8ff;
    font-family: Arial, sans-serif;
}

h1 {
    color: darkblue;
}

This file will style your template.

8. Loading Static Files in a Template

Before using static files in a Django template, you must load the static template tag library.

At the top of your HTML template, add:

{% load static %}

Then link your CSS file like this:

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

Full example

{% load static %}
<!DOCTYPE html>
<html>
<head>
    <title>My Blog</title>
    <link rel="stylesheet" href="{% static 'blog/css/style.css' %}">
</head>
<body>
    <h1>Welcome to my blog</h1>
</body>
</html>

Now your CSS file is correctly connected.

9. Using JavaScript Files

You can also add JavaScript files in the same way.

File path

blog/static/blog/js/script.js

Example content

console.log("JavaScript is working!");

Template usage

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

Example

{% load static %}
<!DOCTYPE html>
<html>
<head>
    <title>My Blog</title>
</head>
<body>
    <h1>Welcome</h1>

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

This allows you to add behavior and interactivity.

10. Using Images in Templates

Images can also be stored as static files.

File path

blog/static/blog/images/logo.png

Template usage

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

Example

{% load static %}
<img src="{% static 'blog/images/logo.png' %}" alt="My Blog Logo">

This is useful for logos, icons, banners, and decorative images.

11. Example of a Full Template with Static Files


{% load static %}
<!DOCTYPE html>
<html>
<head>
    <title>Blog Home</title>
    <link rel="stylesheet" href="{% static 'blog/css/style.css' %}">
</head>
<body>
    <img src="{% static 'blog/images/logo.png' %}" alt="Logo" width="100">
    <h1>Welcome to My Blog</h1>
    <p>This page uses static CSS and images.</p>

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

This simple example combines HTML, CSS, JavaScript, and an image.

12. App-Level Static Files vs Project-Level Static Files

There are two common ways to organize static files.

Option 1: Inside each app

Example:

blog/static/blog/css/style.css

This is very common and clean for reusable apps.

Option 2: Global project-level static folder

Example:

project_root/
├── static/
│   ├── css/
│   ├── js/
│   └── images/

This is often used for project-wide assets shared by many apps.

13. Using a Global Static Directory

If you want a shared static folder at the project level, add this to settings.py:

from pathlib import Path

BASE_DIR = Path(__file__).resolve().parent.parent

STATIC_URL = 'static/'
STATICFILES_DIRS = [
    BASE_DIR / 'static',
]

What this does

It tells Django to also search for static files in the project-level static/ folder.

This is useful for:

  • shared CSS
  • global JavaScript
  • common images
  • site-wide frontend assets

14. Example of Global Static Usage

Suppose you have:

project_root/
├── static/
│   └── css/
│       └── main.css

Then in your template:

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

This works because Django now knows about the global static folder.

15. Static Files During Development

When DEBUG = True, Django can serve static files automatically during development.

This means if your project is running locally with:

python manage.py runserver

Django will handle your static files for you.

This is convenient for learning and testing.

16. Static Files in Production

In production, static files are usually handled differently.

Django does not usually serve static files directly in a production setup. Instead, they are often served by:

  • Nginx
  • Apache
  • a CDN
  • a cloud storage service

To prepare static files for production, Django uses:

python manage.py collectstatic

This collects static assets into a single directory for deployment.

Beginner note

For now, it is enough to understand that:

  • during development, Django serves static files
  • during production, a web server often serves them

You will learn this more deeply in deployment tutorials.

17. What Is collectstatic?

collectstatic is a Django management command that gathers all static files from apps and project folders into one destination directory.

This is useful in production.

Typical production setting:

STATIC_ROOT = BASE_DIR / 'staticfiles'

Then run:

python manage.py collectstatic

This copies static files into the staticfiles/ directory.

18. Common Beginner Mistakes

Mistake 1: Forgetting {% load static %}

If you do not load the static tag library, this will not work:

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

Mistake 2: Wrong file path

If the path is incorrect, Django will not find the file.

Example:

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

when the actual file is:

blog/static/blog/css/style.css

The correct path is:

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

Mistake 3: Putting static files in the wrong folder

Files should be stored in a recognized static directory.

Mistake 4: Confusing static and media

A logo you created for the site is static.
A profile picture uploaded by a user is media.

Mistake 5: Forgetting to refresh browser cache

Sometimes CSS changes do not appear immediately because the browser caches static files.

19. Best Practices

  • keep static files organized by type
  • use app names in file paths
  • separate CSS, JS, and images into folders
  • use a global static folder for shared assets
  • avoid duplicate file names
  • keep filenames meaningful

A clean example:

static/
├── css/
│   └── main.css
├── js/
│   └── app.js
└── images/
    └── logo.png

And for app-specific assets:

blog/static/blog/css/post.css

This makes projects easier to maintain.

20. Real Example: Styling a Blog Homepage

CSS file

blog/static/blog/css/style.css
body {
    background-color: #eef2f7;
    font-family: Arial, sans-serif;
}

h1 {
    color: #1e3a8a;
    text-align: center;
}

p {
    color: #333;
}

Template

{% load static %}
<!DOCTYPE html>
<html>
<head>
    <title>Blog Home</title>
    <link rel="stylesheet" href="{% static 'blog/css/style.css' %}">
</head>
<body>
    <h1>Welcome to My Blog</h1>
    <p>This page is styled with a static CSS file.</p>
</body>
</html>

 

When you run the server and open the page, the design will look much better.

21. Beginner Analogy

Think of your Django template as a house.

  • the HTML is the structure of the house
  • the CSS is the paint and decoration
  • the JavaScript is the electricity and automation
  • the images are the furniture and visual design

Without static files, the house exists, but it does not feel complete.

22. Summary

In this tutorial, you learned what static files are and why they are important in Django. You saw how to create static folders, add CSS, JavaScript, and images, and load them into templates using {% load static %} and the {% static %} tag. You also learned the difference between app-level and project-level static files, and got a first introduction to collectstatic for production.

This is a key step in making your Django websites look professional and interactive.

23. Key Takeaways

  • static files include CSS, JavaScript, images, icons, and fonts
  • STATIC_URL defines the public path for static files
  • {% load static %} must be used in templates
  • {% static 'path/to/file' %} generates file URLs
  • app-level static folders help organize assets
  • STATICFILES_DIRS can add a global static folder
  • collectstatic prepares static files for production

24. Small Knowledge Check

  1. What are static files in Django?
  2. What is the difference between static files and media files?
  3. Why do you need {% load static %} in templates?
  4. How do you link a CSS file in a Django template?
  5. What does collectstatic do?

25. Conclusion

Static files are what transform a simple Django page into a real website with design and interactivity. Once you understand how static files work, you can begin building pages that are not only functional, but also attractive and user-friendly.