Fix Django Media Files Not Serving (Uploads Broken in Production)

If your Django app uploads files successfully but:

• Images don’t load
• User uploads return 404
• Media URLs are broken

👉 Then your media files are not being served correctly

This guide will walk you through how to fix it step-by-step.

⚡ Quick Fix (Try This First)

Run:

sudo systemctl restart gunicorn
sudo systemctl restart nginx

Then check a media file URL:

http://your-domain/media/your-file.jpg

👉 If still broken, continue below.

🧠 What’s Happening

In production:

• Django does NOT serve media files
• Nginx must serve them

If uploads are broken, it usually means:

Nginx cannot find or access your media directory

🧪 Step-by-Step Diagnosis

Follow these steps in order.

1. Check MEDIA_ROOT setting

In settings.py:

MEDIA_ROOT = '/var/www/myproject/media/'
MEDIA_URL = '/media/'

👉 This defines where uploaded files are stored

2. Verify files exist

ls /var/www/myproject/media/

You should see:

• Uploaded images/files

👉 If empty:

• If not, then uploads are not working. Check your upload code.
• Upload process is broken (not Nginx)

3. Test media URL directly

Open in browser:

http://your-domain/media/your-file.jpg

If 404:

• Nginx is not serving media

If works:

• Problem is elsewhere (templates, paths)

4. Check Nginx configuration

Open config:

sudo nano /etc/nginx/sites-available/myproject

or your favorite editor.

Ensure this exists:

location /media/ {
    root /var/www/myproject;
}

👉 Important:

• /media/ maps to /var/www/myproject/media/

5. Test Nginx config

sudo nginx -t

Then:

sudo systemctl restart nginx

6. Check file permissions

sudo chown -R www-data:www-data /var/www/myproject
sudo chmod -R 755 /var/www/myproject

👉 Nginx must be able to read media files

🔥 Common Causes (and Fixes)

🔴 MEDIA_ROOT is incorrect

Fix:

MEDIA_ROOT = '/var/www/myproject/media/'

🔴 Nginx not configured for media

Add:

location /media/ {
    root /var/www/myproject;
}

🔴 Permissions issue

Fix:

sudo chown -R www-data:www-data /var/www/myproject

🔴 Files stored in wrong location

Check upload path:

Django might be saving elsewhere

🔴 MEDIA_URL incorrect

MEDIA_URL = '/media/'

🧠 Debugging Tips

Check Nginx logs

sudo tail -f /var/log/nginx/error.log

Look for:

• 404
• permission denied

Check browser DevTools

• Network tab → failed requests
• Look for:
  • 404 errors
  • incorrect URLs

Check Django upload path

If using ImageField or FileField:

upload_to='uploads/'

✅ Quick Fix Checklist

• MEDIA_ROOT is correct
• MEDIA_URL is /media/
• Files exist in media folder
• Nginx config includes /media/
• Permissions are correct
• Nginx restarted

🔗 Related Guides

• Django static files not loading
• Deploy Django with Nginx + Gunicorn
• Fix Django 502 Bad Gateway

❓ FAQ

What’s the difference between static and media files?

• Static: CSS, JS (part of your code)
• Media: user uploads (dynamic content)

Can Django serve media files?

Only in development:

DEBUG = True

In production:

👉 Use Nginx or a CDN to serve media files for better performance and security.

Why do uploads work but files don’t load?

Because:

• Files are saved
• But not served by Nginx

🎯 Final takeaway

If media files are broken:

It’s almost always:

• Nginx config
• File permissions
• MEDIA_ROOT mismatch

Fix those, and uploads will work correctly.

If you deploy often…

A repeatable, pre-tested setup will save hours of debugging.