<!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.11 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.11', 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.11 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.11 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.11 documentation</a> <ul><li><a href="../index.html">API Reference</a> <ul><li><a href="index.html"><tt class="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">Apr 24, 2014</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>