Media Handling

This document explains how Pinax handles media files across external and internal applications and themes.

Basic media handling

If you want to override default media files, place yours under <project_name>/media/… with the same path. For example:

Original file:


Your file:


Locations of media files

If you want to use Pinax’ media handling with your own Django apps, please make sure you put the media files like JavaScript, cascading stylesheets (CSS) and images in the following directory structure:


Doubling your <app_name> is required to prevent name collision of media files while deploying.

Site specific media files goes to:


The special static file service view should be able to serve the media files in development.

build_media management command

The build_media script collects the media files from Pinax and all the installed apps and arranges them under the <project_name>/site_media/static folder.

The command:

<project_name>/python build_media --all

will collect the media files from Pinax and all the apps and places them in the folder defined in the STATIC_ROOT setting.

If you have two apps with the same file and the same relative path it’s advised to use the --interactive option so the script will prompt you to choose which one to use. This is useful in case you want to overwrite default media files with your custom app for example. Remember to remove the site_media folder before you use this option or the script will prompt you for each file.

Please also refer to the help of the build_media management command by running:

<project_name>/python build_media --help

resolve_media management command

To quickly resolve the full file path of a media file on the filesystem, you can pass its expected URL path(s) to the resolve_media management command, e.g.:

$ ./manage resolve_media pinax/css/base.css
Resolving css/site_tabs.css:

If multiple locations are found which match the given path it will list all of them, sorted by its importance.

Serving static files during development

Pinax provides the static file serving view staticfiles.views.serve to handle the app and theme media as well as other media files found in the MEDIA_ROOT directory. Make sure your projects’ contains the following snippet below the rest of the url configuration:

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