Skip to content

Mastering Django Static File Settings: STATIC_URL, STATIC_ROOT & STATICFILES_DIRS

Django's static file settings are configuration options in the settings.py file that control how static files (such as CSS, JavaScript, and images) are managed and served in a Django project.

Overview

Static files are essential for adding styles, scripts, and images to your web application, and Django provides a structured way to handle these files both during development and in production.

Mastering Django Static File Settings: From STATIC_URL to STATICFILES_DIRS

How Static Files Work

1. Development:

  • During development, Django uses the STATIC_URL setting to serve static files directly.
  • The STATICFILES_DIRS setting allows you to include additional directories for static files.

2. Production:

  • When deploying, you run python manage.py collectstatic to gather all static files into the directory specified by STATIC_ROOT.
  • Static files are then served by the web server (e.g., Nginx, Apache) rather than by Django itself.

Example Configuration

Here's a sample configuration that might be used in a Django project:

# settings.py

# URL prefix for serving static files
STATIC_URL = '/static/'

# Additional directories to search for static files
STATICFILES_DIRS = [
    os.path.join(BASE_DIR, 'assets'),
]

# Directory where static files will be collected for production
STATIC_ROOT = os.path.join(BASE_DIR, 'staticfiles')

# Storage backend for static files (optional)
STATICFILES_STORAGE = 'django.contrib.staticfiles.storage.StaticFilesStorage'

# Finders for locating static files (optional)
STATICFILES_FINDERS = [
    'django.contrib.staticfiles.finders.FileSystemFinder',
    'django.contrib.staticfiles.finders.AppDirectoriesFinder',
]

Summary

Django's static file settings provide a framework for managing static assets in your project. They help you configure how static files are served and collected, ensuring that your CSS, JavaScript, and images are available to users both during development and in production.

Explanation

1. STATIC_URL

Purpose:

  • STATIC_URL defines the URL prefix for serving static files. It tells Django where static files can be accessed from the web.

Manual Folder Creation:

  • You do not need to create a folder manually for STATIC_URL. This setting is for defining the URL path, not a file system path.

Configuration:

  • Type: String
  • Required: Yes
  • Typical Value: /static/
STATIC_URL = '/static/'

This means that static files will be served at URLs starting with /static/, such as http://example.com/static/css/style.css.

2. STATIC_ROOT

Purpose:

STATIC_ROOT specifies the directory where all static files will be collected when you run the collectstatic command. This is used in production to gather all static files into one place so that they can be served efficiently by a web server.

Manual Folder Creation:

  • You do not need to manually create the STATIC_ROOT folder before running collectstatic. Django will create this folder for you if it does not already exist. However, ensure that the directory is writable by the user running the Django application.

Configuration:

  • Type: String (directory path)
  • Required: No, but it is necessary for production environments.
  • Typical Value: os.path.join(BASE_DIR, 'staticfiles')
STATIC_ROOT = os.path.join(BASE_DIR, 'staticfiles')

This means that when you run python manage.py collectstatic, all your static files will be gathered into the staticfiles directory inside your project’s base directory.

3. STATICFILES_DIRS

Purpose:

STATICFILES_DIRS is a list of additional directories where Django should look for static files, in addition to each app’s static directory. It’s useful for specifying global static file locations outside of individual apps.

Manual Folder Creation:

  • Yes, you need to manually create the folders listed in STATICFILES_DIRS if they do not already exist. For example, if you specify assets in STATICFILES_DIRS, you should create the assets folder in your project directory and place your static files there.

Configuration:

  • Type: List of strings (directory paths)
  • Required: No, but useful if you need to add global directories for static files.
  • Typical Value: [os.path.join(BASE_DIR, 'assets')]
STATICFILES_DIRS = [
    os.path.join(BASE_DIR, 'assets'),
]

This tells Django to also look in the assets directory at the base level of your project for static files.

Summary

  • STATIC_URL: Defines the URL path to access static files. No manual folder creation is needed.
  • STATIC_ROOT: Directory where static files are collected for production. Django creates this folder during the collectstatic process if it does not exist.
  • STATICFILES_DIRS: List of additional directories to search for static files. You need to manually create these directories and place static files in them.

By configuring these settings properly and creating necessary directories, you ensure that Django can correctly manage and serve static files both during development and in production.

Advanced

In Django, a top-level directory for global static files is a directory located at the root of your project directory that is used to store static files that are not tied to any specific Django app but are shared across the entire project. This directory is an optional but useful organization technique for managing static assets that you want to be accessible throughout your project but are not directly associated with any particular application.

Purpose of a Top-Level Global Static Directory

  • Centralization: Keeps global static files in one place rather than scattering them across different apps.
  • Organization: Helps in maintaining a clear structure by separating static files used across the project from those specific to individual apps.
  • Convenience: Provides an easy way to manage and reference global assets, such as site-wide CSS or JavaScript files, that are used throughout the project.
myproject/
    myapp1/
        static/
            myapp1/
                css/
                js/
                images/
    myapp2/
        static/
            myapp2/
                css/
                js/
                images/
    assets/  # This is the global static directory
        css/
        js/
        images/
    myproject/
        __init__.py
        settings.py
        urls.py
        wsgi.py
    manage.py
settings.py
import os
from pathlib import Path

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


# URL prefix for serving static files
STATIC_URL = '/static/'

# Directory where static files will be collected for production
STATIC_ROOT = os.path.join(BASE_DIR, 'staticfiles')

# Additional directories where Django will look for static files
STATICFILES_DIRS = [
    os.path.join(BASE_DIR, 'assets'),  # Global static directory
]
Explanation
  • STATIC_URL: Defines the base URL for serving static files. In this case, /static/ means that static files will be served at URLs starting with /static/.
  • STATICFILES_DIRS: Lists additional directories for Django to search for static files. The assets directory is specified here, so Django will also look in myproject/assets/ for static files.

Using Static Files in Templates

When you use static files in your Django templates, you will reference them with the URL defined by STATIC_URL. For example:

<!-- Linking a CSS file from the global assets directory -->
<link rel="stylesheet" type="text/css" href="{% static 'css/style.css' %}" />

In this case, Django will look for style.css in the assets/css/ directory and serve it at http://example.com/static/css/style.css.

Summary

  • Top-Level Global Static Directory: A directory like assets/ at the root level of your project that stores static files shared across the entire project.
  • Purpose: Centralizes and organizes global static files that are not specific to any particular app.
  • Configuration: Use the STATICFILES_DIRS setting in settings.py to include this directory in Django's static file search paths.

By organizing your static files this way, you can maintain a clear and manageable structure, especially in larger projects where multiple apps and global assets are involved.

Hidden Magic

python3 manage.py shell

List all the seetings

from django.conf import settings
dir(settings)

diffsettings

Running python manage.py diffsettings will show you the settings that differ from the default values. This can be useful to see which static file settings have been explicitly defined in your project.

python manage.py diffsettings