Static Files

Static Files#

This page provides a comprehensive guide covering all aspects of Django static files management. Here are the key points to highlight:

  • The guide covers both development and production configurations

  • Shows multiple methods for overriding third-party static files

  • Includes best practices for organization and performance

  • Provides example configurations for popular deployment options

👉 New to App-Generator? Sign IN with GitHub or Generate Web Apps in no time (free service).

Basic Setup#

Settings Configuration#

# settings.py # Base directory for static files collection STATIC_URL = '/static/' STATIC_ROOT = BASE_DIR / 'staticfiles' # Where collectstatic will collect files # Additional locations of static files STATICFILES_DIRS = [ BASE_DIR / 'static', # Your project's static files ] # Static file finders - how Django looks for static files STATICFILES_FINDERS = [ 'django.contrib.staticfiles.finders.FileSystemFinder', # Looks in STATICFILES_DIRS 'django.contrib.staticfiles.finders.AppDirectoriesFinder', # Looks in app/static/ ]

Project Structure#

myproject/ ├── myproject/ │ ├── settings.py │ └── urls.py ├── static/ # Project-level static files │ ├── css/ │ ├── js/ │ └── images/ ├── myapp/ │ └── static/ # App-level static files │ └── myapp/ # Namespace to avoid conflicts │ ├── css/ │ ├── js/ │ └── images/ └── staticfiles/ # Collected static files (production)

Development vs Production#

Development#

# settings/development.py DEBUG = True # Django's development server will automatically serve static files # No need to run collectstatic

Production#

# settings/production.py DEBUG = False # Additional settings for production STATIC_ROOT = BASE_DIR / 'staticfiles' STATICFILES_STORAGE = 'django.contrib.staticfiles.storage.ManifestStaticFilesStorage' # Optional: Configure compression and caching STATICFILES_STORAGE = 'django.contrib.staticfiles.storage.CompressedManifestStaticFilesStorage'

Collecting Static Files#

# Collect all static files to STATIC_ROOT python manage.py collectstatic # Force collection even if files exist python manage.py collectstatic --clear --no-input

Overriding Third-Party Static Files#

Method 1: Using STATICFILES_DIRS#

# settings.py STATICFILES_DIRS = [ # Override specific files from third-party packages ('admin/css/base.css', '/path/to/your/custom/base.css'), # General static files directory BASE_DIR / 'static', ]

Method 2: App-Level Override#

myapp/ └── static/  └── third_party_app/ # Same name as the app you're overriding  └── css/  └── style.css # File to override

Method 3: Using Template Loading Order#

# settings.py INSTALLED_APPS = [ 'myapp', # Your app first 'third_party_app', # Third-party app second # ... other apps ]

Using Static Files in Templates#

Template Tags#

{% load static %} <!-- Basic usage --> <link href="{% static 'css/style.css' %}" rel="stylesheet"> <img src="{% static 'images/logo.png' %}" alt="Logo"> <!-- With variables --> <img src="{% static image_path %}" alt="{{ image_alt }}">

Handling Missing Files#

# settings.py STATIC_URL = '/static/' STATICFILES_STORAGE = 'django.contrib.staticfiles.storage.ManifestStaticFilesStorage' # Optional: Custom storage class for better error handling from django.contrib.staticfiles.storage import ManifestStaticFilesStorage class CustomManifestStaticFilesStorage(ManifestStaticFilesStorage): def hashed_name(self, name, content=None, filename=None): try: result = super().hashed_name(name, content, filename) except ValueError: # Return original name if hashing fails result = name return result

Serving Static Files in Production#

Using Whitenoise#

# settings.py MIDDLEWARE = [ # ... 'whitenoise.middleware.WhiteNoiseMiddleware', ] # WhiteNoise configuration STATICFILES_STORAGE = 'whitenoise.storage.CompressedManifestStaticFilesStorage' # Optional: Enable Brotli compression WHITENOISE_USE_FINDERS = True WHITENOISE_COMPRESSION_QUALITY = 100

Using Nginx#

# nginx.conf server {  # ...  location /static/ {  alias /path/to/your/staticfiles/;  expires 30d;  add_header Cache-Control "public, no-transform";  } }

Best Practices#

Using Content Delivery Networks (CDN)#

# settings.py # Use different static URLs based on environment if not DEBUG: STATIC_URL = 'https://your-cdn.com/static/'

Organizing Static Files#

# Use namespaced folders to avoid conflicts STATICFILES_DIRS = [ BASE_DIR / 'static' / 'common', # Shared assets BASE_DIR / 'static' / 'vendor', # Third-party assets ]

Cache Control#

# settings.py AWS_S3_OBJECT_PARAMETERS = { # If using S3 'CacheControl': 'max-age=86400', } # Or in nginx location /static/ { expires max; add_header Cache-Control "public, no-transform"; }