This is a Django app that provides helpers for serving static files.

The main website for django-staticfiles is where you can also file tickets.

You can also install the in-development version of django-staticfiles with pip install django-staticfiles==dev or easy_install django-staticfiles==dev.

Management Commands


Collects the media files from all installed apps and copies them to the STATICFILES_STORAGE.

You can limit the apps parsed by providing a list of app names:

$ python build_static --exclude-dirs admin polls

Duplicate file names are resolved in a similar way to how template resolution works. Files are initially searched for in STATICFILES_DIRS locations, followed by apps in the order specified by the INSTALLED_APPS setting.

Some commonly used options are:

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.
Exclude additional static locations specified in the STATICFILES_DIRS setting.

For a full list of options, refer to the build_static management command help by running:

$ python build_static --help


Resolves one or more expected relative URL path to absolute paths of each media file on the filesystem. For example:

$ python resolve_static css/base.css admin/js/core.css

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

$ python resolve_static css/base.css --first

static_url context processor

To refer to static file assets from a template, ensure you have set the STATIC_URL setting to the URL path where the static files are served.

Next, add the static_url context processor to your TEMPLATE_CONTEXT_PROCESSORS setting:


Templates rendered with RequestContext will now have access to a STATIC_URL context variable:

<link href="{{ STATIC_URL }}css/polls.css" rel="stylesheet" type="text/css" />

Serving static files during development


Don't use this on production servers. This feature is only intended for development. Please, don't shoot yourself in the foot. Thanks.

To serve static media for both MEDIA_URL and STATIC_URL add the following snippet to your end of your primary URL configuration:

from django.conf import settings
if settings.DEBUG:
    urlpatterns += patterns('',
        (r'', include('staticfiles.urls')),



Default:'' (Empty string)

The absolute path to the directory that holds static files like app media:

STATIC_ROOT = "/home/"

This is only used by the default static files storage (i.e. if you use a different STATICFILES_STORAGE, you don't need to set this).


Default:'' (Empty string)

URL that handles the files served from STATIC_ROOT, e.g.:

STATIC_URL = '/site_media/static/'

Note that this should always have a trailing slash.



This setting defines the additional locations the staticfiles app will traverse when looking for media files, e.g. if you use the build_static or resolve_static management command or use the static file serving view.

It should be defined as a sequence of (prefix, path) tuples, e.g.:

    ('', '/home/'),
    ('', '/home/'),
    ('common', '/opt/webfiles/common'),



A sequence of app paths that should be prefixed with the label name. For example, django.contrib.admin media files should be served from admin/[js,css,images] rather than the media files getting served directly from the static root.



A sequence of directory names to be used when searching for media files in installed apps, e.g. if an app has its media files in <app>/static use:




A sequence of app paths that should be ignored when searching for media files:




The storage to use for copying static files to a single location.



  • Renamed build_media and resolve_media management commands to *_static as to avoid confusions between Django's use of the term "media" (for uploads) and "static" files.
  • Rework most of the internal logic, abstracting the core functionality away from the management commands.

v0.1.2 (2009-09-02):

  • Fixed a typo in
  • Fixed a conflict in build_media (now build_static) between handling non-namespaced app media and other files with the same relative path.

v0.1.1 (2009-09-02):

  • Added README with a bit of documentation :)

v0.1.0 (2009-09-02):

  • Initial checkin from Pinax' source.
  • Will create the STATIC_ROOT directory if not existent.