<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>The staticfiles app — Django 1.4.5 documentation</title>
<link rel="stylesheet" href="../../_static/default.css" type="text/css" />
<link rel="stylesheet" href="../../_static/pygments.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '../../',
VERSION: '1.4.5',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true
};
</script>
<script type="text/javascript" src="../../_static/jquery.js"></script>
<script type="text/javascript" src="../../_static/underscore.js"></script>
<script type="text/javascript" src="../../_static/doctools.js"></script>
<link rel="top" title="Django 1.4.5 documentation" href="../../index.html" />
<link rel="up" title="contrib packages" href="index.html" />
<link rel="next" title="The syndication feed framework" href="syndication.html" />
<link rel="prev" title="The “sites” framework" href="sites.html" />
<script type="text/javascript" src="../../templatebuiltins.js"></script>
<script type="text/javascript">
(function($) {
if (!django_template_builtins) {
// templatebuiltins.js missing, do nothing.
return;
}
$(document).ready(function() {
// Hyperlink Django template tags and filters
var base = "../templates/builtins.html";
if (base == "#") {
// Special case for builtins.html itself
base = "";
}
// Tags are keywords, class '.k'
$("div.highlight\\-html\\+django span.k").each(function(i, elem) {
var tagname = $(elem).text();
if ($.inArray(tagname, django_template_builtins.ttags) != -1) {
var fragment = tagname.replace(/_/, '-');
$(elem).html("<a href='" + base + "#" + fragment + "'>" + tagname + "</a>");
}
});
// Filters are functions, class '.nf'
$("div.highlight\\-html\\+django span.nf").each(function(i, elem) {
var filtername = $(elem).text();
if ($.inArray(filtername, django_template_builtins.tfilters) != -1) {
var fragment = filtername.replace(/_/, '-');
$(elem).html("<a href='" + base + "#" + fragment + "'>" + filtername + "</a>");
}
});
});
})(jQuery);
</script>
</head>
<body>
<div class="document">
<div id="custom-doc" class="yui-t6">
<div id="hd">
<h1><a href="../../index.html">Django 1.4.5 documentation</a></h1>
<div id="global-nav">
<a title="Home page" href="../../index.html">Home</a> |
<a title="Table of contents" href="../../contents.html">Table of contents</a> |
<a title="Global index" href="../../genindex.html">Index</a> |
<a title="Module index" href="../../py-modindex.html">Modules</a>
</div>
<div class="nav">
« <a href="sites.html" title="The &#8220;sites&#8221; framework">previous</a>
|
<a href="../index.html" title="API Reference" accesskey="U">up</a>
|
<a href="syndication.html" title="The syndication feed framework">next</a> »</div>
</div>
<div id="bd">
<div id="yui-main">
<div class="yui-b">
<div class="yui-g" id="ref-contrib-staticfiles">
<div class="section" id="s-module-django.contrib.staticfiles">
<span id="s-the-staticfiles-app"></span><span id="module-django.contrib.staticfiles"></span><span id="the-staticfiles-app"></span><h1>The staticfiles app<a class="headerlink" href="#module-django.contrib.staticfiles" title="Permalink to this headline">¶</a></h1>
<div class="versionadded">
<span class="title">New in Django 1.3:</span> <a class="reference internal" href="../../releases/1.3.html"><em>Please see the release notes</em></a></div>
<p><tt class="docutils literal"><span class="pre">django.contrib.staticfiles</span></tt> 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.</p>
<div class="admonition-see-also admonition seealso">
<p class="first admonition-title">See also</p>
<p class="last">For an introduction to the static files app and some usage examples, see
<a class="reference internal" href="../../howto/static-files.html"><em>Managing static files</em></a>.</p>
</div>
<div class="section" id="s-settings">
<span id="s-staticfiles-settings"></span><span id="settings"></span><span id="staticfiles-settings"></span><h2>Settings<a class="headerlink" href="#settings" title="Permalink to this headline">¶</a></h2>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">The following settings control the behavior of the staticfiles app.</p>
</div>
<div class="section" id="s-staticfiles-dirs">
<span id="s-std:setting-STATICFILES_DIRS"></span><span id="staticfiles-dirs"></span><span id="std:setting-STATICFILES_DIRS"></span><h3>STATICFILES_DIRS<a class="headerlink" href="#staticfiles-dirs" title="Permalink to this headline">¶</a></h3>
<p>Default: <tt class="docutils literal"><span class="pre">[]</span></tt></p>
<p>This setting defines the additional locations the staticfiles app will traverse
if the <tt class="xref py py-class docutils literal"><span class="pre">FileSystemFinder</span></tt> finder is enabled, e.g. if you use the
<a class="reference internal" href="#django-admin-collectstatic"><tt class="xref std std-djadmin docutils literal"><span class="pre">collectstatic</span></tt></a> or <a class="reference internal" href="#django-admin-findstatic"><tt class="xref std std-djadmin docutils literal"><span class="pre">findstatic</span></tt></a> management command or use the
static file serving view.</p>
<p>This should be set to a list or tuple of strings that contain full paths to
your additional files directory(ies) e.g.:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">STATICFILES_DIRS</span> <span class="o">=</span> <span class="p">(</span>
<span class="s">"/home/special.polls.com/polls/static"</span><span class="p">,</span>
<span class="s">"/home/polls.com/polls/static"</span><span class="p">,</span>
<span class="s">"/opt/webfiles/common"</span><span class="p">,</span>
<span class="p">)</span>
</pre></div>
</div>
<div class="section" id="s-prefixes-optional">
<span id="prefixes-optional"></span><h4>Prefixes (optional)<a class="headerlink" href="#prefixes-optional" title="Permalink to this headline">¶</a></h4>
<p>In case you want to refer to files in one of the locations with an additional
namespace, you can <strong>optionally</strong> provide a prefix as <tt class="docutils literal"><span class="pre">(prefix,</span> <span class="pre">path)</span></tt>
tuples, e.g.:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">STATICFILES_DIRS</span> <span class="o">=</span> <span class="p">(</span>
<span class="c"># ...</span>
<span class="p">(</span><span class="s">"downloads"</span><span class="p">,</span> <span class="s">"/opt/webfiles/stats"</span><span class="p">),</span>
<span class="p">)</span>
</pre></div>
</div>
<p>Example:</p>
<p>Assuming you have <a class="reference internal" href="../settings.html#std:setting-STATIC_URL"><tt class="xref std std-setting docutils literal"><span class="pre">STATIC_URL</span></tt></a> set <tt class="docutils literal"><span class="pre">'/static/'</span></tt>, the
<a class="reference internal" href="#django-admin-collectstatic"><tt class="xref std std-djadmin docutils literal"><span class="pre">collectstatic</span></tt></a> management command would collect the “stats” files
in a <tt class="docutils literal"><span class="pre">'downloads'</span></tt> subdirectory of <a class="reference internal" href="../settings.html#std:setting-STATIC_ROOT"><tt class="xref std std-setting docutils literal"><span class="pre">STATIC_ROOT</span></tt></a>.</p>
<p>This would allow you to refer to the local file
<tt class="docutils literal"><span class="pre">'/opt/webfiles/stats/polls_20101022.tar.gz'</span></tt> with
<tt class="docutils literal"><span class="pre">'/static/downloads/polls_20101022.tar.gz'</span></tt> in your templates, e.g.:</p>
<div class="highlight-html+django"><div class="highlight"><pre><span class="nt"><a</span> <span class="na">href=</span><span class="s">"</span><span class="cp">{{</span> <span class="nv">STATIC_URL</span> <span class="cp">}}</span><span class="s">downloads/polls_20101022.tar.gz"</span><span class="nt">></span>
</pre></div>
</div>
</div>
</div>
<div class="section" id="s-staticfiles-storage">
<span id="s-std:setting-STATICFILES_STORAGE"></span><span id="staticfiles-storage"></span><span id="std:setting-STATICFILES_STORAGE"></span><h3>STATICFILES_STORAGE<a class="headerlink" href="#staticfiles-storage" title="Permalink to this headline">¶</a></h3>
<p>Default: <tt class="docutils literal"><span class="pre">'django.contrib.staticfiles.storage.StaticFilesStorage'</span></tt></p>
<p>The file storage engine to use when collecting static files with the
<a class="reference internal" href="#django-admin-collectstatic"><tt class="xref std std-djadmin docutils literal"><span class="pre">collectstatic</span></tt></a> management command.</p>
<div class="versionadded">
<span class="title">New in Django 1.4:</span> <a class="reference internal" href="../../releases/1.4.html"><em>Please see the release notes</em></a></div>
<p>A ready-to-use instance of the storage backend defined in this setting
can be found at <tt class="docutils literal"><span class="pre">django.contrib.staticfiles.storage.staticfiles_storage</span></tt>.</p>
<p>For an example, see <a class="reference internal" href="../../howto/static-files.html#staticfiles-from-cdn"><em>Serving static files from a cloud service or CDN</em></a>.</p>
</div>
<div class="section" id="s-staticfiles-finders">
<span id="s-std:setting-STATICFILES_FINDERS"></span><span id="staticfiles-finders"></span><span id="std:setting-STATICFILES_FINDERS"></span><h3>STATICFILES_FINDERS<a class="headerlink" href="#staticfiles-finders" title="Permalink to this headline">¶</a></h3>
<p>Default:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="p">(</span><span class="s">"django.contrib.staticfiles.finders.FileSystemFinder"</span><span class="p">,</span>
<span class="s">"django.contrib.staticfiles.finders.AppDirectoriesFinder"</span><span class="p">)</span>
</pre></div>
</div>
<p>The list of finder backends that know how to find static files in
various locations.</p>
<p>The default will find files stored in the <a class="reference internal" href="#std:setting-STATICFILES_DIRS"><tt class="xref std std-setting docutils literal"><span class="pre">STATICFILES_DIRS</span></tt></a> setting
(using <tt class="xref py py-class docutils literal"><span class="pre">django.contrib.staticfiles.finders.FileSystemFinder</span></tt>) and in a
<tt class="docutils literal"><span class="pre">static</span></tt> subdirectory of each app (using
<tt class="xref py py-class docutils literal"><span class="pre">django.contrib.staticfiles.finders.AppDirectoriesFinder</span></tt>)</p>
<p>One finder is disabled by default:
<tt class="xref py py-class docutils literal"><span class="pre">django.contrib.staticfiles.finders.DefaultStorageFinder</span></tt>. If added to
your <a class="reference internal" href="#std:setting-STATICFILES_FINDERS"><tt class="xref std std-setting docutils literal"><span class="pre">STATICFILES_FINDERS</span></tt></a> setting, it will look for static files in
the default file storage as defined by the <a class="reference internal" href="../settings.html#std:setting-DEFAULT_FILE_STORAGE"><tt class="xref std std-setting docutils literal"><span class="pre">DEFAULT_FILE_STORAGE</span></tt></a>
setting.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">When using the <tt class="xref py py-class docutils literal"><span class="pre">AppDirectoriesFinder</span></tt> finder, make sure your apps
can be found by staticfiles. Simply add the app to the
<a class="reference internal" href="../settings.html#std:setting-INSTALLED_APPS"><tt class="xref std std-setting docutils literal"><span class="pre">INSTALLED_APPS</span></tt></a> setting of your site.</p>
</div>
<p>Static file finders are currently considered a private interface, and this
interface is thus undocumented.</p>
</div>
</div>
<div class="section" id="s-management-commands">
<span id="management-commands"></span><h2>Management Commands<a class="headerlink" href="#management-commands" title="Permalink to this headline">¶</a></h2>
<p><tt class="docutils literal"><span class="pre">django.contrib.staticfiles</span></tt> exposes three management commands.</p>
<div class="section" id="s-collectstatic">
<span id="collectstatic"></span><h3>collectstatic<a class="headerlink" href="#collectstatic" title="Permalink to this headline">¶</a></h3>
<dl class="django-admin">
<dt id="django-admin-collectstatic">
<tt class="descname">django-admin.py collectstatic</tt><a class="headerlink" href="#django-admin-collectstatic" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<p>Collects the static files into <a class="reference internal" href="../settings.html#std:setting-STATIC_ROOT"><tt class="xref std std-setting docutils literal"><span class="pre">STATIC_ROOT</span></tt></a>.</p>
<p>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 <a class="reference internal" href="#django-admin-findstatic"><tt class="xref std std-djadmin docutils literal"><span class="pre">findstatic</span></tt></a> command
can help show you which files are found.</p>
<p>Files are searched by using the <a class="reference internal" href="#std:setting-STATICFILES_FINDERS"><tt class="xref std std-setting docutils literal"><span class="pre">enabled</span> <span class="pre">finders</span></tt></a>. The default is to look in all locations defined in
<a class="reference internal" href="#std:setting-STATICFILES_DIRS"><tt class="xref std std-setting docutils literal"><span class="pre">STATICFILES_DIRS</span></tt></a> and in the <tt class="docutils literal"><span class="pre">'static'</span></tt> directory of apps
specified by the <a class="reference internal" href="../settings.html#std:setting-INSTALLED_APPS"><tt class="xref std std-setting docutils literal"><span class="pre">INSTALLED_APPS</span></tt></a> setting.</p>
<div class="versionadded">
<span class="title">New in Django 1.4:</span> <a class="reference internal" href="../../releases/1.4.html"><em>Please see the release notes</em></a></div>
<p>The <a class="reference internal" href="#django-admin-collectstatic"><tt class="xref std std-djadmin docutils literal"><span class="pre">collectstatic</span></tt></a> management command calls the
<a class="reference internal" href="#django.contrib.staticfiles.storage.StaticFilesStorage.post_process" title="django.contrib.staticfiles.storage.StaticFilesStorage.post_process"><tt class="xref py py-meth docutils literal"><span class="pre">post_process()</span></tt></a>
method of the <a class="reference internal" href="#std:setting-STATICFILES_STORAGE"><tt class="xref std std-setting docutils literal"><span class="pre">STATICFILES_STORAGE</span></tt></a> after each run and passes
a list of paths that have been found by the management command. It also
receives all command line options of <a class="reference internal" href="#django-admin-collectstatic"><tt class="xref std std-djadmin docutils literal"><span class="pre">collectstatic</span></tt></a>. This is used
by the <a class="reference internal" href="#django.contrib.staticfiles.storage.CachedStaticFilesStorage" title="django.contrib.staticfiles.storage.CachedStaticFilesStorage"><tt class="xref py py-class docutils literal"><span class="pre">CachedStaticFilesStorage</span></tt></a>
by default.</p>
<p>Some commonly used options are:</p>
<dl class="django-admin-option">
<dt id="django-admin-option---noinput">
<tt class="descname">--noinput</tt><tt class="descclassname"></tt><a class="headerlink" href="#django-admin-option---noinput" title="Permalink to this definition">¶</a></dt>
<dd><p>Do NOT prompt the user for input of any kind.</p>
</dd></dl>
<dl class="django-admin-option">
<dt id="django-admin-option--i">
<tt class="descname">-i</tt><tt class="descclassname"> <pattern></tt><a class="headerlink" href="#django-admin-option--i" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<dl class="django-admin-option">
<dt id="django-admin-option---ignore">
<tt class="descname">--ignore</tt><tt class="descclassname"> <pattern></tt><a class="headerlink" href="#django-admin-option---ignore" title="Permalink to this definition">¶</a></dt>
<dd><p>Ignore files or directories matching this glob-style pattern. Use multiple
times to ignore more.</p>
</dd></dl>
<dl class="django-admin-option">
<dt id="django-admin-option--n">
<tt class="descname">-n</tt><tt class="descclassname"></tt><a class="headerlink" href="#django-admin-option--n" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<dl class="django-admin-option">
<dt id="django-admin-option---dry-run">
<tt class="descname">--dry-run</tt><tt class="descclassname"></tt><a class="headerlink" href="#django-admin-option---dry-run" title="Permalink to this definition">¶</a></dt>
<dd><p>Do everything except modify the filesystem.</p>
</dd></dl>
<dl class="django-admin-option">
<dt id="django-admin-option--c">
<tt class="descname">-c</tt><tt class="descclassname"></tt><a class="headerlink" href="#django-admin-option--c" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<dl class="django-admin-option">
<dt id="django-admin-option---clear">
<tt class="descname">--clear</tt><tt class="descclassname"></tt><a class="headerlink" href="#django-admin-option---clear" title="Permalink to this definition">¶</a></dt>
<dd><div class="versionadded">
<span class="title">New in Django 1.4:</span> <a class="reference internal" href="../../releases/1.4.html"><em>Please see the release notes</em></a></div>
<p>Clear the existing files before trying to copy or link the original file.</p>
</dd></dl>
<dl class="django-admin-option">
<dt id="django-admin-option--l">
<tt class="descname">-l</tt><tt class="descclassname"></tt><a class="headerlink" href="#django-admin-option--l" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<dl class="django-admin-option">
<dt id="django-admin-option---link">
<tt class="descname">--link</tt><tt class="descclassname"></tt><a class="headerlink" href="#django-admin-option---link" title="Permalink to this definition">¶</a></dt>
<dd><p>Create a symbolic link to each file instead of copying.</p>
</dd></dl>
<dl class="django-admin-option">
<dt id="django-admin-option---no-post-process">
<tt class="descname">--no-post-process</tt><tt class="descclassname"></tt><a class="headerlink" href="#django-admin-option---no-post-process" title="Permalink to this definition">¶</a></dt>
<dd><div class="versionadded">
<span class="title">New in Django 1.4:</span> <a class="reference internal" href="../../releases/1.4.html"><em>Please see the release notes</em></a></div>
<p>Don’t call the
<a class="reference internal" href="#django.contrib.staticfiles.storage.StaticFilesStorage.post_process" title="django.contrib.staticfiles.storage.StaticFilesStorage.post_process"><tt class="xref py py-meth docutils literal"><span class="pre">post_process()</span></tt></a>
method of the configured <a class="reference internal" href="#std:setting-STATICFILES_STORAGE"><tt class="xref std std-setting docutils literal"><span class="pre">STATICFILES_STORAGE</span></tt></a> storage backend.</p>
</dd></dl>
<dl class="django-admin-option">
<dt id="django-admin-option---no-default-ignore">
<tt class="descname">--no-default-ignore</tt><tt class="descclassname"></tt><a class="headerlink" href="#django-admin-option---no-default-ignore" title="Permalink to this definition">¶</a></dt>
<dd><p>Don’t ignore the common private glob-style patterns <tt class="docutils literal"><span class="pre">'CVS'</span></tt>, <tt class="docutils literal"><span class="pre">'.*'</span></tt>
and <tt class="docutils literal"><span class="pre">'*~'</span></tt>.</p>
</dd></dl>
<p>For a full list of options, refer to the commands own help by running:</p>
<div class="highlight-console"><div class="highlight"><pre><span class="gp">$</span> python manage.py collectstatic --help
</pre></div>
</div>
</div>
<div class="section" id="s-findstatic">
<span id="findstatic"></span><h3>findstatic<a class="headerlink" href="#findstatic" title="Permalink to this headline">¶</a></h3>
<dl class="django-admin">
<dt id="django-admin-findstatic">
<tt class="descname">django-admin.py findstatic</tt><a class="headerlink" href="#django-admin-findstatic" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<p>Searches for one or more relative paths with the enabled finders.</p>
<p>For example:</p>
<div class="highlight-console"><div class="highlight"><pre><span class="gp">$</span> python manage.py findstatic css/base.css admin/js/core.js
<span class="go">/home/special.polls.com/core/static/css/base.css</span>
<span class="go">/home/polls.com/core/static/css/base.css</span>
<span class="go">/home/polls.com/src/django/contrib/admin/media/js/core.js</span>
</pre></div>
</div>
<p>By default, all matching locations are found. To only return the first match
for each relative path, use the <tt class="docutils literal"><span class="pre">--first</span></tt> option:</p>
<div class="highlight-console"><div class="highlight"><pre><span class="gp">$</span> python manage.py findstatic css/base.css --first
<span class="go">/home/special.polls.com/core/static/css/base.css</span>
</pre></div>
</div>
<p>This is a debugging aid; it’ll show you exactly which static file will be
collected for a given path.</p>
</div>
<div class="section" id="s-runserver">
<span id="s-staticfiles-runserver"></span><span id="runserver"></span><span id="staticfiles-runserver"></span><h3>runserver<a class="headerlink" href="#runserver" title="Permalink to this headline">¶</a></h3>
<dl class="django-admin">
<dt id="django-admin-runserver">
<tt class="descname">django-admin.py runserver</tt><a class="headerlink" href="#django-admin-runserver" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<p>Overrides the core <a class="reference internal" href="../django-admin.html#django-admin-runserver"><tt class="xref std std-djadmin docutils literal"><span class="pre">runserver</span></tt></a> command if the <tt class="docutils literal"><span class="pre">staticfiles</span></tt> app
is <a class="reference internal" href="../settings.html#std:setting-INSTALLED_APPS"><tt class="xref std std-setting docutils literal"><span class="pre">installed</span></tt></a> and adds automatic serving of static
files and the following new options.</p>
<dl class="django-admin-option">
<dt id="django-admin-option---nostatic">
<tt class="descname">--nostatic</tt><tt class="descclassname"></tt><a class="headerlink" href="#django-admin-option---nostatic" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<p>Use the <tt class="docutils literal"><span class="pre">--nostatic</span></tt> option to disable serving of static files with the
<a class="reference internal" href=""><em>staticfiles</em></a> app entirely. This option is
only available if the <a class="reference internal" href=""><em>staticfiles</em></a> app is
in your project’s <a class="reference internal" href="../settings.html#std:setting-INSTALLED_APPS"><tt class="xref std std-setting docutils literal"><span class="pre">INSTALLED_APPS</span></tt></a> setting.</p>
<p>Example usage:</p>
<div class="highlight-console"><div class="highlight"><pre><span class="go">django-admin.py runserver --nostatic</span>
</pre></div>
</div>
<dl class="django-admin-option">
<dt id="django-admin-option---insecure">
<tt class="descname">--insecure</tt><tt class="descclassname"></tt><a class="headerlink" href="#django-admin-option---insecure" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<p>Use the <tt class="docutils literal"><span class="pre">--insecure</span></tt> option to force serving of static files with the
<a class="reference internal" href=""><em>staticfiles</em></a> app even if the <a class="reference internal" href="../settings.html#std:setting-DEBUG"><tt class="xref std std-setting docutils literal"><span class="pre">DEBUG</span></tt></a>
setting is <tt class="docutils literal"><span class="pre">False</span></tt>. By using this you acknowledge the fact that it’s
<strong>grossly inefficient</strong> and probably <strong>insecure</strong>. This is only intended for
local development, should <strong>never be used in production</strong> and is only
available if the <a class="reference internal" href=""><em>staticfiles</em></a> app is
in your project’s <a class="reference internal" href="../settings.html#std:setting-INSTALLED_APPS"><tt class="xref std std-setting docutils literal"><span class="pre">INSTALLED_APPS</span></tt></a> setting.</p>
<p>Example usage:</p>
<div class="highlight-console"><div class="highlight"><pre><span class="go">django-admin.py runserver --insecure</span>
</pre></div>
</div>
</div>
</div>
<div class="section" id="s-storages">
<span id="storages"></span><h2>Storages<a class="headerlink" href="#storages" title="Permalink to this headline">¶</a></h2>
<div class="section" id="s-staticfilesstorage">
<span id="staticfilesstorage"></span><h3>StaticFilesStorage<a class="headerlink" href="#staticfilesstorage" title="Permalink to this headline">¶</a></h3>
<dl class="class">
<dt id="django.contrib.staticfiles.storage.StaticFilesStorage">
<em class="property">class </em><tt class="descclassname">storage.</tt><tt class="descname">StaticFilesStorage</tt><a class="headerlink" href="#django.contrib.staticfiles.storage.StaticFilesStorage" title="Permalink to this definition">¶</a></dt>
<dd><p>A subclass of the <a class="reference internal" href="../files/storage.html#django.core.files.storage.FileSystemStorage" title="django.core.files.storage.FileSystemStorage"><tt class="xref py py-class docutils literal"><span class="pre">FileSystemStorage</span></tt></a>
storage backend that uses the <a class="reference internal" href="../settings.html#std:setting-STATIC_ROOT"><tt class="xref std std-setting docutils literal"><span class="pre">STATIC_ROOT</span></tt></a> setting as the base
file system location and the <a class="reference internal" href="../settings.html#std:setting-STATIC_URL"><tt class="xref std std-setting docutils literal"><span class="pre">STATIC_URL</span></tt></a> setting respectively
as the base URL.</p>
<dl class="method">
<dt id="django.contrib.staticfiles.storage.StaticFilesStorage.post_process">
<tt class="descname">post_process</tt>(<em>paths</em>, <em>**options</em>)<a class="headerlink" href="#django.contrib.staticfiles.storage.StaticFilesStorage.post_process" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<div class="versionadded">
<span class="title">New in Django 1.4:</span> <a class="reference internal" href="../../releases/1.4.html"><em>Please see the release notes</em></a></div>
<p>This method is called by the <a class="reference internal" href="#django-admin-collectstatic"><tt class="xref std std-djadmin docutils literal"><span class="pre">collectstatic</span></tt></a> management command
after each run and gets passed the local storages and paths of found
files as a dictionary, as well as the command line options.</p>
<p>The <a class="reference internal" href="#django.contrib.staticfiles.storage.CachedStaticFilesStorage" title="django.contrib.staticfiles.storage.CachedStaticFilesStorage"><tt class="xref py py-class docutils literal"><span class="pre">CachedStaticFilesStorage</span></tt></a>
uses this behind the scenes to replace the paths with their hashed
counterparts and update the cache appropriately.</p>
</dd></dl>
</div>
<div class="section" id="s-cachedstaticfilesstorage">
<span id="cachedstaticfilesstorage"></span><h3>CachedStaticFilesStorage<a class="headerlink" href="#cachedstaticfilesstorage" title="Permalink to this headline">¶</a></h3>
<dl class="class">
<dt id="django.contrib.staticfiles.storage.CachedStaticFilesStorage">
<em class="property">class </em><tt class="descclassname">storage.</tt><tt class="descname">CachedStaticFilesStorage</tt><a class="headerlink" href="#django.contrib.staticfiles.storage.CachedStaticFilesStorage" title="Permalink to this definition">¶</a></dt>
<dd><div class="versionadded">
<span class="title">New in Django 1.4:</span> <a class="reference internal" href="../../releases/1.4.html"><em>Please see the release notes</em></a></div>
<p>A subclass of the <a class="reference internal" href="#django.contrib.staticfiles.storage.StaticFilesStorage" title="django.contrib.staticfiles.storage.StaticFilesStorage"><tt class="xref py py-class docutils literal"><span class="pre">StaticFilesStorage</span></tt></a>
storage backend which caches the files it saves by appending the MD5 hash
of the file’s content to the filename. For example, the file
<tt class="docutils literal"><span class="pre">css/styles.css</span></tt> would also be saved as <tt class="docutils literal"><span class="pre">css/styles.55e7cbb9ba48.css</span></tt>.</p>
<p>The purpose of this storage is to keep serving the old files in case some
pages still refer to those files, e.g. because they are cached by you or
a 3rd party proxy server. Additionally, it’s very helpful if you want to
apply <a class="reference external" href="http://developer.yahoo.com/performance/rules.html#expires">far future Expires headers</a> to the deployed files to speed up the
load time for subsequent page visits.</p>
<p>The storage backend automatically replaces the paths found in the saved
files matching other saved files with the path of the cached copy (using
the <a class="reference internal" href="#django.contrib.staticfiles.storage.StaticFilesStorage.post_process" title="django.contrib.staticfiles.storage.StaticFilesStorage.post_process"><tt class="xref py py-meth docutils literal"><span class="pre">post_process()</span></tt></a>
method). The regular expressions used to find those paths
(<tt class="docutils literal"><span class="pre">django.contrib.staticfiles.storage.CachedStaticFilesStorage.cached_patterns</span></tt>)
by default cover the <a class="reference external" href="http://www.w3.org/TR/CSS2/cascade.html#at-import">@import</a> rule and <a class="reference external" href="http://www.w3.org/TR/CSS2/syndata.html#uri">url()</a> statement of <a class="reference external" href="http://www.w3.org/Style/CSS/">Cascading
Style Sheets</a>. For example, the <tt class="docutils literal"><span class="pre">'css/styles.css'</span></tt> file with the
content</p>
<div class="highlight-css+django"><div class="highlight"><pre><span class="k">@import</span> <span class="nt">url</span><span class="o">(</span><span class="s2">"../admin/css/base.css"</span><span class="o">)</span><span class="p">;</span>
</pre></div>
</div>
<p>would be replaced by calling the
<a class="reference internal" href="../files/storage.html#django.core.files.storage.Storage.url" title="django.core.files.storage.Storage.url"><tt class="xref py py-meth docutils literal"><span class="pre">url()</span></tt></a>
method of the <tt class="docutils literal"><span class="pre">CachedStaticFilesStorage</span></tt> storage backend, ultimatively
saving a <tt class="docutils literal"><span class="pre">'css/styles.55e7cbb9ba48.css'</span></tt> file with the following
content:</p>
<div class="highlight-css+django"><div class="highlight"><pre><span class="k">@import</span> <span class="nt">url</span><span class="o">(</span><span class="s2">"../admin/css/base.27e20196a850.css"</span><span class="o">)</span><span class="p">;</span>
</pre></div>
</div>
<p>To enable the <tt class="docutils literal"><span class="pre">CachedStaticFilesStorage</span></tt> you have to make sure the
following requirements are met:</p>
<ul class="simple">
<li>the <a class="reference internal" href="#std:setting-STATICFILES_STORAGE"><tt class="xref std std-setting docutils literal"><span class="pre">STATICFILES_STORAGE</span></tt></a> setting is set to
<tt class="docutils literal"><span class="pre">'django.contrib.staticfiles.storage.CachedStaticFilesStorage'</span></tt></li>
<li>the <a class="reference internal" href="../settings.html#std:setting-DEBUG"><tt class="xref std std-setting docutils literal"><span class="pre">DEBUG</span></tt></a> setting is set to <tt class="docutils literal"><span class="pre">False</span></tt></li>
<li>you use the <tt class="docutils literal"><span class="pre">staticfiles</span></tt> <a class="reference internal" href="#std:templatetag-staticfiles-static"><tt class="xref std std-ttag docutils literal"><span class="pre">static</span></tt></a> template
tag to refer to your static files in your templates</li>
<li>you’ve collected all your static files by using the
<a class="reference internal" href="#django-admin-collectstatic"><tt class="xref std std-djadmin docutils literal"><span class="pre">collectstatic</span></tt></a> management command</li>
</ul>
<p>Since creating the MD5 hash can be a performance burden to your website
during runtime, <tt class="docutils literal"><span class="pre">staticfiles</span></tt> will automatically try to cache the
hashed name for each file path using Django’s <a class="reference internal" href="../../topics/cache.html"><em>caching
framework</em></a>. If you want to override certain options of the
cache backend the storage uses, simply specify a custom entry in the
<a class="reference internal" href="../settings.html#std:setting-CACHES"><tt class="xref std std-setting docutils literal"><span class="pre">CACHES</span></tt></a> setting named <tt class="docutils literal"><span class="pre">'staticfiles'</span></tt>. It falls back to using
the <tt class="docutils literal"><span class="pre">'default'</span></tt> cache backend.</p>
</dd></dl>
</div>
</div>
<div class="section" id="s-template-tags">
<span id="template-tags"></span><h2>Template tags<a class="headerlink" href="#template-tags" title="Permalink to this headline">¶</a></h2>
<div class="section" id="s-static">
<span id="static"></span><h3>static<a class="headerlink" href="#static" title="Permalink to this headline">¶</a></h3>
<div class="versionadded" id="std:templatetag-staticfiles-static">
<span class="title">New in Django 1.4:</span> <a class="reference internal" href="../../releases/1.4.html"><em>Please see the release notes</em></a></div>
<p>Uses the configured <a class="reference internal" href="#std:setting-STATICFILES_STORAGE"><tt class="xref std std-setting docutils literal"><span class="pre">STATICFILES_STORAGE</span></tt></a> storage to create the
full URL for the given relative path, e.g.:</p>
<div class="highlight-html+django"><div class="highlight"><pre><span class="cp">{%</span> <span class="k">load</span> <span class="nv">static</span> <span class="nv">from</span> <span class="nv">staticfiles</span> <span class="cp">%}</span>
<span class="nt"><img</span> <span class="na">src=</span><span class="s">"</span><span class="cp">{%</span> <span class="k">static</span> <span class="s2">"css/base.css"</span> <span class="cp">%}</span><span class="s">"</span> <span class="nt">/></span>
</pre></div>
</div>
<p>The previous example is equal to calling the <tt class="docutils literal"><span class="pre">url</span></tt> method of an instance of
<a class="reference internal" href="#std:setting-STATICFILES_STORAGE"><tt class="xref std std-setting docutils literal"><span class="pre">STATICFILES_STORAGE</span></tt></a> with <tt class="docutils literal"><span class="pre">"css/base.css"</span></tt>. This is especially
useful when using a non-local storage backend to deploy files as documented
in <a class="reference internal" href="../../howto/static-files.html#staticfiles-from-cdn"><em>Serving static files from a cloud service or CDN</em></a>.</p>
</div>
</div>
<div class="section" id="s-other-helpers">
<span id="other-helpers"></span><h2>Other Helpers<a class="headerlink" href="#other-helpers" title="Permalink to this headline">¶</a></h2>
<p>There are a few other helpers outside of the
<a class="reference internal" href="#module-django.contrib.staticfiles" title="django.contrib.staticfiles: An app for handling static files."><tt class="xref py py-mod docutils literal"><span class="pre">staticfiles</span></tt></a> app to work with static
files:</p>
<ul class="simple">
<li>The <a class="reference internal" href="../templates/api.html#django.core.context_processors.static" title="django.core.context_processors.static"><tt class="xref py py-func docutils literal"><span class="pre">django.core.context_processors.static()</span></tt></a> context processor
which adds <a class="reference internal" href="../settings.html#std:setting-STATIC_URL"><tt class="xref std std-setting docutils literal"><span class="pre">STATIC_URL</span></tt></a> to every template context rendered
with <a class="reference internal" href="../templates/api.html#django.template.RequestContext" title="django.template.RequestContext"><tt class="xref py py-class docutils literal"><span class="pre">RequestContext</span></tt></a> contexts.</li>
<li>The builtin template tag <a class="reference internal" href="../templates/builtins.html#std:templatetag-static"><tt class="xref std std-ttag docutils literal"><span class="pre">static</span></tt></a> which takes a path and
urljoins it with the static prefix <a class="reference internal" href="../settings.html#std:setting-STATIC_URL"><tt class="xref std std-setting docutils literal"><span class="pre">STATIC_URL</span></tt></a>.</li>
<li>The builtin template tag <a class="reference internal" href="../templates/builtins.html#std:templatetag-get_static_prefix"><tt class="xref std std-ttag docutils literal"><span class="pre">get_static_prefix</span></tt></a> which populates a
template variable with the static prefix <a class="reference internal" href="../settings.html#std:setting-STATIC_URL"><tt class="xref std std-setting docutils literal"><span class="pre">STATIC_URL</span></tt></a> to be
used as a variable or directly.</li>
<li>The similar template tag <a class="reference internal" href="../templates/builtins.html#std:templatetag-get_media_prefix"><tt class="xref std std-ttag docutils literal"><span class="pre">get_media_prefix</span></tt></a> which works like
<a class="reference internal" href="../templates/builtins.html#std:templatetag-get_static_prefix"><tt class="xref std std-ttag docutils literal"><span class="pre">get_static_prefix</span></tt></a> but uses <a class="reference internal" href="../settings.html#std:setting-MEDIA_URL"><tt class="xref std std-setting docutils literal"><span class="pre">MEDIA_URL</span></tt></a>.</li>
</ul>
<div class="section" id="s-static-file-development-view">
<span id="s-staticfiles-development-view"></span><span id="static-file-development-view"></span><span id="staticfiles-development-view"></span><h3>Static file development view<a class="headerlink" href="#static-file-development-view" title="Permalink to this headline">¶</a></h3>
<dl class="function">
<dt id="django.contrib.staticfiles.templatetags.staticfiles.django.contrib.staticfiles.views.serve">
<tt class="descclassname">django.contrib.staticfiles.views.</tt><tt class="descname">serve</tt>(<em>request</em>, <em>path</em>)<a class="headerlink" href="#django.contrib.staticfiles.templatetags.staticfiles.django.contrib.staticfiles.views.serve" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<p>This view function serves static files in development.</p>
<div class="admonition warning">
<p class="first admonition-title">Warning</p>
<p>This view will only work if <a class="reference internal" href="../settings.html#std:setting-DEBUG"><tt class="xref std std-setting docutils literal"><span class="pre">DEBUG</span></tt></a> is <tt class="docutils literal"><span class="pre">True</span></tt>.</p>
<p class="last">That’s because this view is <strong>grossly inefficient</strong> and probably
<strong>insecure</strong>. This is only intended for local development, and should
<strong>never be used in production</strong>.</p>
</div>
<p>This view is automatically enabled by <a class="reference internal" href="../django-admin.html#django-admin-runserver"><tt class="xref std std-djadmin docutils literal"><span class="pre">runserver</span></tt></a> (with a
<a class="reference internal" href="../settings.html#std:setting-DEBUG"><tt class="xref std std-setting docutils literal"><span class="pre">DEBUG</span></tt></a> setting set to <tt class="docutils literal"><span class="pre">True</span></tt>). To use the view with a different
local development server, add the following snippet to the end of your
primary URL configuration:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">django.conf</span> <span class="kn">import</span> <span class="n">settings</span>
<span class="k">if</span> <span class="n">settings</span><span class="o">.</span><span class="n">DEBUG</span><span class="p">:</span>
<span class="n">urlpatterns</span> <span class="o">+=</span> <span class="n">patterns</span><span class="p">(</span><span class="s">'django.contrib.staticfiles.views'</span><span class="p">,</span>
<span class="n">url</span><span class="p">(</span><span class="s">r'^static/(?P<path>.*)$'</span><span class="p">,</span> <span class="s">'serve'</span><span class="p">),</span>
<span class="p">)</span>
</pre></div>
</div>
<p>Note, the beginning of the pattern (<tt class="docutils literal"><span class="pre">r'^static/'</span></tt>) should be your
<a class="reference internal" href="../settings.html#std:setting-STATIC_URL"><tt class="xref std std-setting docutils literal"><span class="pre">STATIC_URL</span></tt></a> setting.</p>
<p>Since this is a bit finicky, there’s also a helper function that’ll do this for you:</p>
<dl class="function">
<dt id="django.contrib.staticfiles.templatetags.staticfiles.django.contrib.staticfiles.urls.staticfiles_urlpatterns">
<tt class="descclassname">django.contrib.staticfiles.urls.</tt><tt class="descname">staticfiles_urlpatterns</tt>()<a class="headerlink" href="#django.contrib.staticfiles.templatetags.staticfiles.django.contrib.staticfiles.urls.staticfiles_urlpatterns" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<p>This will return the proper URL pattern for serving static files to your
already defined pattern list. Use it like this:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">django.contrib.staticfiles.urls</span> <span class="kn">import</span> <span class="n">staticfiles_urlpatterns</span>
<span class="c"># ... the rest of your URLconf here ...</span>
<span class="n">urlpatterns</span> <span class="o">+=</span> <span class="n">staticfiles_urlpatterns</span><span class="p">()</span>
</pre></div>
</div>
<div class="admonition warning">
<p class="first admonition-title">Warning</p>
<p class="last">This helper function will only work if <a class="reference internal" href="../settings.html#std:setting-DEBUG"><tt class="xref std std-setting docutils literal"><span class="pre">DEBUG</span></tt></a> is <tt class="docutils literal"><span class="pre">True</span></tt>
and your <a class="reference internal" href="../settings.html#std:setting-STATIC_URL"><tt class="xref std std-setting docutils literal"><span class="pre">STATIC_URL</span></tt></a> setting is neither empty nor a full
URL such as <tt class="docutils literal"><span class="pre">http://static.example.com/</span></tt>.</p>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="yui-b" id="sidebar">
<div class="sphinxsidebar">
<div class="sphinxsidebarwrapper">
<h3><a href="../../contents.html">Table Of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">The staticfiles app</a><ul>
<li><a class="reference internal" href="#settings">Settings</a><ul>
<li><a class="reference internal" href="#staticfiles-dirs">STATICFILES_DIRS</a><ul>
<li><a class="reference internal" href="#prefixes-optional">Prefixes (optional)</a></li>
</ul>
</li>
<li><a class="reference internal" href="#staticfiles-storage">STATICFILES_STORAGE</a></li>
<li><a class="reference internal" href="#staticfiles-finders">STATICFILES_FINDERS</a></li>
</ul>
</li>
<li><a class="reference internal" href="#management-commands">Management Commands</a><ul>
<li><a class="reference internal" href="#collectstatic">collectstatic</a></li>
<li><a class="reference internal" href="#findstatic">findstatic</a></li>
<li><a class="reference internal" href="#runserver">runserver</a></li>
</ul>
</li>
<li><a class="reference internal" href="#storages">Storages</a><ul>
<li><a class="reference internal" href="#staticfilesstorage">StaticFilesStorage</a></li>
<li><a class="reference internal" href="#cachedstaticfilesstorage">CachedStaticFilesStorage</a></li>
</ul>
</li>
<li><a class="reference internal" href="#template-tags">Template tags</a><ul>
<li><a class="reference internal" href="#static">static</a></li>
</ul>
</li>
<li><a class="reference internal" href="#other-helpers">Other Helpers</a><ul>
<li><a class="reference internal" href="#static-file-development-view">Static file development view</a></li>
</ul>
</li>
</ul>
</li>
</ul>
<h3>Browse</h3>
<ul>
<li>Prev: <a href="sites.html">The “sites” framework</a></li>
<li>Next: <a href="syndication.html">The syndication feed framework</a></li>
</ul>
<h3>You are here:</h3>
<ul>
<li>
<a href="../../index.html">Django 1.4.5 documentation</a>
<ul><li><a href="../index.html">API Reference</a>
<ul><li><a href="index.html"><tt class="docutils literal docutils literal docutils literal docutils literal docutils literal docutils literal docutils literal docutils literal docutils literal docutils literal docutils literal docutils literal docutils literal docutils literal docutils literal docutils literal docutils literal docutils literal docutils literal docutils literal docutils literal docutils literal docutils literal docutils literal docutils literal docutils literal docutils literal docutils literal docutils literal docutils literal docutils literal docutils literal docutils literal docutils literal docutils literal docutils literal docutils literal docutils literal docutils literal docutils literal docutils literal docutils literal docutils literal docutils literal docutils literal docutils literal docutils literal docutils literal docutils literal docutils literal"><span class="pre">contrib</span></tt> packages</a>
<ul><li>The staticfiles app</li></ul>
</li></ul></li></ul>
</li>
</ul>
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../../_sources/ref/contrib/staticfiles.txt"
rel="nofollow">Show Source</a></li>
</ul>
<div id="searchbox" style="display: none">
<h3>Quick search</h3>
<form class="search" action="../../search.html" method="get">
<input type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
<p class="searchtip" style="font-size: 90%">
Enter search terms or a module, class or function name.
</p>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<h3>Last update:</h3>
<p class="topless">Feb 21, 2013</p>
</div>
</div>
<div id="ft">
<div class="nav">
« <a href="sites.html" title="The &#8220;sites&#8221; framework">previous</a>
|
<a href="../index.html" title="API Reference" accesskey="U">up</a>
|
<a href="syndication.html" title="The syndication feed framework">next</a> »</div>
</div>
</div>
<div class="clearer"></div>
</div>
</body>
</html>
