The staticfiles app

Novo no Django 1.3: Please, see the release notes

django.contrib.staticfiles collects static files from each of your applications (and any other places you specify) into a single location that can easily be served in production.

See also

For an introduction to the static files app and some usage examples, see Managing static files.

Settings

Note

The following settings control the behavior of the staticfiles app.

STATICFILES_DIRS

Default: []

This setting defines the additional locations the staticfiles app will traverse if the FileSystemFinder finder is enabled, e.g. if you use the collectstatic or findstatic management command or use the static file serving view.

This should be set to a list or tuple of strings that contain full paths to your additional files directory(ies) e.g.:

STATICFILES_DIRS = (
    "/home/special.polls.com/polls/static",
    "/home/polls.com/polls/static",
    "/opt/webfiles/common",
)

Prefixes (optional)

In case you want to refer to files in one of the locations with an additional namespace, you can optionally provide a prefix as (prefix, path) tuples, e.g.:

STATICFILES_DIRS = (
    # ...
    ("downloads", "/opt/webfiles/stats"),
)

Example:

Assuming you have STATIC_URL set '/static/', the collectstatic management command would collect the "stats" files in a 'downloads' subdirectory of STATIC_ROOT.

This would allow you to refer to the local file '/opt/webfiles/stats/polls_20101022.tar.gz' with '/static/downloads/polls_20101022.tar.gz' in your templates, e.g.:

<a href="{{ STATIC_URL }}downloads/polls_20101022.tar.gz">

STATICFILES_STORAGE

Default: 'django.contrib.staticfiles.storage.StaticFilesStorage'

The file storage engine to use when collecting static files with the collectstatic management command.

For an example, see Serving static files from a cloud service or CDN.

STATICFILES_FINDERS

Default:

("django.contrib.staticfiles.finders.FileSystemFinder",
 "django.contrib.staticfiles.finders.AppDirectoriesFinder")

The list of finder backends that know how to find static files in various locations.

The default will find files stored in the STATICFILES_DIRS setting (using django.contrib.staticfiles.finders.FileSystemFinder) and in a static subdirectory of each app (using django.contrib.staticfiles.finders.AppDirectoriesFinder)

One finder is disabled by default: django.contrib.staticfiles.finders.DefaultStorageFinder. If added to your STATICFILES_FINDERS setting, it will look for static files in the default file storage as defined by the DEFAULT_FILE_STORAGE setting.

Note

When using the AppDirectoriesFinder finder, make sure your apps can be found by staticfiles. Simply add the app to the INSTALLED_APPS setting of your site.

Static file finders are currently considered a private interface, and this interface is thus undocumented.

Management Commands

django.contrib.staticfiles exposes three management commands.

collectstatic

django-admin.py collectstatic

Collects the static files into STATIC_ROOT.

Duplicate file names are by default resolved in a similar way to how template resolution works: the file that is first found in one of the specified locations will be used. If you're confused, the findstatic command can help show you which files are found.

Files are searched by using the enabled finders. The default is to look in all locations defined in STATICFILES_DIRS and in the 'static' directory of apps specified by the INSTALLED_APPS setting.

Some commonly used options are:

--noinput
Do NOT prompt the user for input of any kind.
-i PATTERN or --ignore=PATTERN
Ignore files or directories matching this glob-style pattern. Use multiple times to ignore more.
-n or --dry-run
Do everything except modify the filesystem.
-l or --link
Create a symbolic link to each file instead of copying.
--no-default-ignore
Don't ignore the common private glob-style patterns 'CVS', '.*' and '*~'.

For a full list of options, refer to the commands own help by running:

$ python manage.py collectstatic --help

findstatic

django-admin.py findstatic

Searches for one or more relative paths with the enabled finders.

For example:

$ python manage.py findstatic css/base.css admin/js/core.js
/home/special.polls.com/core/static/css/base.css
/home/polls.com/core/static/css/base.css
/home/polls.com/src/django/contrib/admin/media/js/core.js

By default, all matching locations are found. To only return the first match for each relative path, use the --first option:

$ python manage.py findstatic css/base.css --first
/home/special.polls.com/core/static/css/base.css

This is a debugging aid; it'll show you exactly which static file will be collected for a given path.

runserver

django-admin.py runserver

Overrides the core runserver command if the staticfiles app is installed and adds automatic serving of static files and the following new options.

--nostatic

Use the --nostatic option to disable serving of static files with the staticfiles app entirely. This option is only available if the staticfiles app is in your project's INSTALLED_APPS setting.

Example usage:

django-admin.py runserver --nostatic
--insecure

Use the --insecure option to force serving of static files with the staticfiles app even if the DEBUG setting is False. By using this you acknowledge the fact that it's grossly inefficient and probably insecure. This is only intended for local development, should never be used in production and is only available if the staticfiles app is in your project's INSTALLED_APPS setting.

Example usage:

django-admin.py runserver --insecure

Other Helpers

The static context processor

django.core.context_processors.static()

This context processor adds the STATIC_URL into each template context as the variable {{ STATIC_URL }}. To use it, make sure that 'django.core.context_processors.static' appears somewhere in your TEMPLATE_CONTEXT_PROCESSORS setting.

Remember, only templates rendered with RequestContext will have acces to the data provided by this (and any) context processor.

The get_static_prefix templatetag

If you're not using RequestContext, or if you need more control over exactly where and how STATIC_URL is injected into the template, you can use the get_static_prefix template tag instead:

{% load static %}
<img src="{% get_static_prefix %}images/hi.jpg" />

There's also a second form you can use to avoid extra processing if you need the value multiple times:

{% load static %}
{% get_static_prefix as STATIC_PREFIX %}

<img src="{{ STATIC_PREFIX }}images/hi.jpg" />
<img src="{{ STATIC_PREFIX }}images/hi2.jpg" />

Static file development view

django.contrib.staticfiles.views.serve(request, path)

This view function serves static files in development.

Warning

This view will only work if DEBUG is True.

That's because this view is grossly inefficient and probably insecure. This is only intended for local development, and should never be used in production.

This view is automatically enabled by runserver (with a DEBUG setting set to True). To use the view with a different local development server, add the following snippet to the end of your primary URL configuration:

from django.conf import settings

if settings.DEBUG:
    urlpatterns += patterns('django.contrib.staticfiles.views',
        url(r'^static/(?P<path>.*)$', 'serve'),
    )

Note, the beginning of the pattern (r'^static/') should be your STATIC_URL setting.

Since this is a bit finicky, there's also a helper function that'll do this for you:

django.contrib.staticfiles.urls.staticfiles_urlpatterns()

This will return the proper URL pattern for serving static files to your already defined pattern list. Use it like this:

from django.contrib.staticfiles.urls import staticfiles_urlpatterns

# ... the rest of your URLconf here ...

urlpatterns += staticfiles_urlpatterns()

Warning

This helper function will only work if DEBUG is True and your STATIC_URL setting is neither empty nor a full URL such as http://static.example.com/.

« previous | up | next »