How to Serve Media Files in Development in Django

To serve media files in development in Django, set MEDIA_URL and MEDIA_ROOT in your settings.py, then add a URL pattern using django.conf.urls.static.static() in your urls.py. This setup allows Django's development server to serve uploaded media files automatically.

Syntax

To serve media files in development, you need to configure two main settings and update your URL patterns.

• MEDIA_URL: The URL prefix for media files (e.g., /media/).
• MEDIA_ROOT: The absolute filesystem path where media files are stored.
• In urls.py, use static() to serve media files only when DEBUG=True.

python

from django.conf import settings
from django.conf.urls.static import static

# settings.py
MEDIA_URL = '/media/'
MEDIA_ROOT = BASE_DIR / 'media'

# urls.py
from django.urls import path

urlpatterns = [
    # your url patterns here
]

if settings.DEBUG:
    urlpatterns += static(settings.MEDIA_URL, document_root=settings.MEDIA_ROOT)

Example

This example shows a minimal setup to serve media files during development. It assumes you have a media folder in your project root where uploaded files are saved.

python

# settings.py
from pathlib import Path

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

MEDIA_URL = '/media/'
MEDIA_ROOT = BASE_DIR / 'media'

# urls.py
from django.contrib import admin
from django.urls import path
from django.conf import settings
from django.conf.urls.static import static

urlpatterns = [
    path('admin/', admin.site.urls),
]

if settings.DEBUG:
    urlpatterns += static(settings.MEDIA_URL, document_root=settings.MEDIA_ROOT)

Output

Django development server serves media files at URLs starting with /media/ from the media folder in your project root.

Common Pitfalls

Common mistakes when serving media files in development include:

• Not setting MEDIA_ROOT or setting it incorrectly, so Django can't find the files.
• Forgetting to add the static() helper in urls.py, so media URLs return 404 errors.
• Trying to serve media files with DEBUG=False, which Django does not support by default.

Always ensure DEBUG=True in development and never use this method in production.

python

# Wrong way (missing static serving in urls.py)
# urls.py
urlpatterns = [
    path('admin/', admin.site.urls),
]

# Right way (add static serving)
from django.conf import settings
from django.conf.urls.static import static

if settings.DEBUG:
    urlpatterns += static(settings.MEDIA_URL, document_root=settings.MEDIA_ROOT)

Quick Reference

Setting/Code	Purpose	Example
MEDIA_URL	URL prefix for media files	'/media/'
MEDIA_ROOT	Filesystem path to media files	BASE_DIR / 'media'
static() in urls.py	Serve media files in development	urlpatterns += static(settings.MEDIA_URL, document_root=settings.MEDIA_ROOT) if DEBUG

Key Takeaways

Set MEDIA_URL and MEDIA_ROOT in settings.py to define media file paths.

Use django.conf.urls.static.static() in urls.py to serve media files during development.

Ensure DEBUG=True when serving media files with Django's development server.

Never serve media files this way in production; use a dedicated web server instead.

Common errors include missing static() in urls.py or incorrect MEDIA_ROOT paths.