Static files in production — collectstatic, STATIC_ROOT, and why runserver won't cut it

With DEBUG = True, Django's development server serves static files (CSS, JS, images) automatically, straight from each app's static/ directory — genuinely convenient, and genuinely not something Django does in production. The moment DEBUG = False, that automatic serving stops entirely, on purpose (per Django's own docs: runserver serving static files is explicitly a development-only convenience, never intended for production traffic) — a project that never accounted for this deploys with every CSS/JS/image link returning 404, while every actual page still loads fine, which is exactly confusing enough to eat real debugging time on a first deploy.

STATICFILES_DIRS tells Django where to find static files beyond each app's own static/ folder — this is a development-time discovery setting. STATIC_ROOT is a completely different thing: it's the single destination directory that collectstatic (below) copies every static file into, gathered from every app and every STATICFILES_DIRS entry, ready to be served by a real web server. Confusing the two is common — STATICFILES_DIRS is about finding files, STATIC_ROOT is about collecting them into one place.

collectstatic walks every installed app's static/ directory plus everything in STATICFILES_DIRS, and copies it all into STATIC_ROOT — one flat, deployable directory. This is a required step in almost every production deploy pipeline (often run automatically as part of a build/deploy script), and it's specifically what a project that only ever ran runserver locally is missing the first time it deploys with DEBUG = False.

Django's own app server (gunicorn, uwsgi) is deliberately not optimized for serving static files efficiently at scale — that's not what it's for. WhiteNoise is the simplest fix for a small-to-medium deploy: it's a piece of middleware that lets the Django process itself serve the collected static files reasonably efficiently, with proper caching headers, without needing to configure a separate web server just for static assets. Larger deployments typically hand this off to nginx or a CDN/object-storage backend instead, for real edge caching and to keep static traffic off the application server entirely.

Without cache-busting, a browser (or CDN) that already cached style.css keeps serving the old version after a deploy, since the filename never changed — a real, common "why isn't my CSS update showing up in production" bug. ManifestStaticFilesStorage renames each collected file to include a content hash (style.a3f5c9.css) and rewrites every reference to it accordingly — a changed file gets a new filename, which is guaranteed to bypass any existing cache, while an unchanged file keeps its old hashed name and stays cached exactly as intended.