Differences between STATICFILES_DIR, STATIC_ROOT and MEDIA_ROOT
Django Settings
STATICFILES_DIRS vs STATIC_ROOT vs MEDIA_ROOT (and STATIC_URL)
Django distinguishes between static assets (CSS, JS, fonts) and user-uploaded media. Knowing where to place each file and how Django serves them keeps your project organized during development and deployment.
Static files
Version-controlled assets such as CSS, JavaScript, and images that ship with your code.
Media files
User-generated uploads (profile pictures, documents) stored separately from static assets.
STATICFILES_DIRS
During development, Django will search for static files in each installed app’s static/ directory. Add STATICFILES_DIRS to point to additional global static folders.
# settings.py
BASE_DIR = Path(__file__).resolve().parent.parent
STATICFILES_DIRS = [
BASE_DIR / "static", # project-level assets
BASE_DIR / "frontend" / "dist" # compiled files from a build tool
]Lookup order: Django searches STATICFILES_DIRS first, then each app’s static folder. It stops at the first match.
STATIC_ROOT
In production you typically serve static files from a single directory (via a CDN, Nginx, or WhiteNoise). STATIC_ROOT points to that directory. Run python manage.py collectstatic to gather assets there.
# settings.py
STATIC_ROOT = BASE_DIR / "staticfiles"After running collectstatic, configure your web server to serve files from STATIC_ROOT.
STATIC_URL
The URL prefix that browsers use to request static assets. In templates, {% load static %} and {% static 'path/to.css' %} combine this prefix with the asset path.
STATIC_URL = "/static/"MEDIA_ROOT
Uploaded files (e.g., ImageField) are stored in MEDIA_ROOT. For local development, serve them with MEDIA_URL via django.conf.urls.static.static(). In production, hand off to cloud storage (S3, GCS) or a web server.
MEDIA_URL = "/media/"
MEDIA_ROOT = BASE_DIR / "media"Quick Reference
| Setting | Used For | Environment |
|---|---|---|
| STATICFILES_DIRS | Additional folders Django searches during development | Development only |
| STATIC_ROOT | Destination directory for collectstatic |
Production (served by web server/CDN) |
| STATIC_URL | URL prefix for static assets | All environments |
| MEDIA_ROOT | Filesystem path for uploaded media | All environments (configure storage per environment) |
Best Practices
Do
- Keep static assets under version control.
- Run
collectstaticas part of your deployment pipeline. - Serve media files from a secure storage backend in production.
Avoid
- Mixing user uploads with version-controlled static files.
- Serving production static files through Django’s development server.
- Hard-coding absolute paths—build paths from
BASE_DIR.