Django Static File Handling

1. Categories of Django Static Files

Django static files fall into two categories: static and media.

static: files referenced by pages, such as JS, CSS, and images
media: files uploaded by users

2. Production Environment Configuration

In production, you usually configure Nginx to forward static file requests while Django handles dynamic requests.

nginx configuration

1
2
3
4
5
6
7
location /media  {
    alias /path/to/project/media;
}

location /static {
    alias /path/to/project/static;
}

When deploying, you need to run the python manage.py collectstatic command to collect the static assets of every Django App in the INSTALLED_APPS list into the directory specified by STATIC_ROOT.

3. Development Environment Configuration

3.1 Configuration and Usage

Step one, add 'django.contrib.staticfiles' to INSTALLED_APPS.

Step two, add the following routes in urls.py. They take effect only when settings.DEBUG==True; in production, Nginx forwards the requests.

1
2
3
4
5
6
7
8
if settings.RUN_MODE == 'DEVELOP':
    urlpatterns += patterns('',
                            url(r'^media/(?P<path>.*)$', 'django.views.static.serve', {
                                'document_root': settings.MEDIA_ROOT,
                            }),
                            url(r'^static/(?P<path>.*)$', 'django.views.static.serve',
                                {'document_root': settings.STATIC_ROOT}),
                            )

Step three, add the following in the settings file under TEMPLATES - OPTIONS - context_processors.

1
2
django.template.context_processors.static
django.template.context_processors.media

Step four, use the STATIC_URL and MEDIA_URL variables in templates.

static files

1
2
3
4
<img src="{{STATIC_URL}}test.png>
#  or
{% load staticfiles %}
<img src="{% static 'img/logo.png' %}">

media files

1
<source src="{{ MEDIA_URL }}movie.ogg" type="video/ogg" />

3.2 Handling Flow

Step one, Django receives a request for a static file, for example /static/css/main.css.

Step two, Django looks for the file css/main.css in STATICFILES_DIRS.

If step two finds it, that file is returned directly; otherwise, Django keeps looking in the static directory of every Django App in the INSTALLED_APPS list.

4.1 STATIC_ROOT

Specifies the directory where static files are stored when the python manage.py collectstatic command runs.

4.2 STATIC_URL

The URL mapping, which specifies the URL of the static directory. The default value is:

1
STATIC_URL = '/static'

4.3 STATICFILES_DIRS

STATICFILES_DIRS is a list that specifies which directories in the project hold static files.

4.4 STATICFILES_STORAGE

The file storage engine Django uses when collecting static files with the python manage.py collectstatic command. If the static files need to be hosted somewhere else, you need to change the STATICFILES_STORAGE parameter and implement the corresponding methods. The default value is:

1
STATICFILES_STORAGE = 'django.contrib.staticfiles.storage.StaticFilesStorage'

4.5 STATICFILES_FINDERS

In a development environment, the order in which django.contrib.staticfiles looks for static assets depends on the STATICFILES_FINDERS configuration. The default STATICFILES_FINDERS configuration is:

1
2
3
4
STATICFILES_FINDERS = (
    'django.contrib.staticfiles.finders.FileSystemFinder',
    'django.contrib.staticfiles.finders.AppDirectoriesFinder',
)

django.contrib.staticfiles.finders.FileSystemFinder looks for static files in the paths specified by STATICFILES_DIRS
django.contrib.staticfiles.finders.AppDirectoriesFinder looks for static files in the static directory of every Django App in the INSTALLED_APPS list

5.1 MEDIA_ROOT

MEDIA stores files uploaded by users, such as the files of a FileField in a Model. If MEDIA_ROOT=C:\media is defined, then with File = models.FileField(upload_to='file/') the uploaded file is saved to C:\media\file.

MEDIA_ROOT set in settings must be an absolute path. You can write it like this:

1
2
3
PROJECT_ROOT = os.path.dirname(os.path.abspath(__file__))
PROJECT_DIR, PROJECT_MODULE_NAME = os.path.split(PROJECT_ROOT)
MEDIA_ROOT = os.path.join(PROJECT_DIR, 'media/')

5.2 MEDIA_URL

MEDIA_URL is the URL prefix used when accessing from a browser, for example:

1
2
MEDIA_ROOT='C:\media\'
MEDIA_URL='/mymedia/'

When the browser visits http://localhost/mymedia/1.png, it is accessing c:\media\1.png.

6. References

http://www.jianshu.com/p/727dc7631274