<!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.6.7 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.6.7', 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.6.7 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.6.7 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> <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/index.html"><em>Managing static files (CSS, images)</em></a>. For guidelines on deploying static files, see <a class="reference internal" href="../../howto/static-files/deployment.html"><em>Deploying 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> <p>See <a class="reference internal" href="../settings.html#settings-staticfiles"><em>staticfiles settings</em></a> for details on the following settings:</p> <ul class="simple"> <li><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></li> <li><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><a class="reference internal" href="../settings.html#std:setting-STATICFILES_DIRS"><tt class="xref std std-setting docutils literal"><span class="pre">STATICFILES_DIRS</span></tt></a></li> <li><a class="reference internal" href="../settings.html#std:setting-STATICFILES_STORAGE"><tt class="xref std std-setting docutils literal"><span class="pre">STATICFILES_STORAGE</span></tt></a></li> <li><a class="reference internal" href="../settings.html#std:setting-STATICFILES_FINDERS"><tt class="xref std std-setting docutils literal"><span class="pre">STATICFILES_FINDERS</span></tt></a></li> </ul> </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="../settings.html#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="../settings.html#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> <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="../settings.html#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><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><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="../settings.html#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">Found 'css/base.css' here:</span> <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">Found 'admin/js/core.js' here:</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">Found 'css/base.css' here:</span> <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> <p>By setting the <a class="reference internal" href="../django-admin.html#django-admin-option---verbosity"><tt class="xref std std-djadminopt docutils literal"><span class="pre">--verbosity</span></tt></a> flag to 0, you can suppress the extra output and just get the path names:</p> <div class="highlight-console"><div class="highlight"><pre><span class="gp">$</span> python manage.py findstatic css/base.css --verbosity 0 <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> </pre></div> </div> </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. <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> <tt class="docutils literal"><span class="pre">--insecure</span></tt> doesn’t work with <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>.</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> <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><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="../settings.html#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> <dl class="method"> <dt id="django.contrib.staticfiles.storage.CachedStaticFilesStorage.file_hash"> <tt class="descname">file_hash</tt>(<em>name</em>, <em>content=None</em>)<a class="headerlink" href="#django.contrib.staticfiles.storage.CachedStaticFilesStorage.file_hash" title="Permalink to this definition">¶</a></dt> <dd></dd></dl> <div class="versionadded"> <span class="title">New in Django 1.5.</span> </div> <p>The method that is used when creating the hashed name of a file. Needs to return a hash for the given file name and content. By default it calculates a MD5 hash from the content’s chunks as mentioned above.</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> <p id="std:templatetag-staticfiles-static">Uses the configured <a class="reference internal" href="../settings.html#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">"images/hi.jpg"</span> <span class="cp">%}</span><span class="s">"</span> <span class="na">alt=</span><span class="s">"Hi!"</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="../settings.html#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">"images/hi.jpg"</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/deployment.html#staticfiles-from-cdn"><em>Serving static files from a cloud service or CDN</em></a>.</p> <div class="versionadded"> <span class="title">New in Django 1.5.</span> </div> <p>If you’d like to retrieve a static URL without displaying it, you can use a slightly different call:</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="cp">{%</span> <span class="k">static</span> <span class="s2">"images/hi.jpg"</span> <span class="k">as</span> <span class="nv">myphoto</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="nv">myphoto</span> <span class="cp">}}</span><span class="s">"</span> <span class="na">alt=</span><span class="s">"Hi!"</span> <span class="nt">/></span> </pre></div> </div> </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> <p>The static files tools are mostly designed to help with getting static files successfully deployed into production. This usually means a separate, dedicated static file server, which is a lot of overhead to mess with when developing locally. Thus, the <tt class="docutils literal"><span class="pre">staticfiles</span></tt> app ships with a <strong>quick and dirty helper view</strong> that you can use to serve files locally in development.</p> <dl class="function"> <dt id="django.contrib.staticfiles.views.serve"> <tt class="descclassname">views.</tt><tt class="descname">serve</tt>(<em>request</em>, <em>path</em>)<a class="headerlink" href="#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> <div class="admonition note"> <p class="first admonition-title">Note</p> <p class="last">To guess the served files’ content types, this view relies on the <tt class="xref py py-mod docutils literal"><span class="pre">mimetypes</span></tt> module from the Python standard library, which itself relies on the underlying platform’s map files. If you find that this view doesn’t return proper content types for certain files, it is most likely that the platform’s map files need to be updated. This can be achieved, for example, by installing or updating the <tt class="docutils literal"><span class="pre">mailcap</span></tt> package on a Red Hat distribution, or <tt class="docutils literal"><span class="pre">mime-support</span></tt> on a Debian distribution.</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.urls.staticfiles_urlpatterns"> <tt class="descclassname">urls.</tt><tt class="descname">staticfiles_urlpatterns</tt>()<a class="headerlink" href="#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> <p>This will inspect 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 and wire up the view to serve static files accordingly. Don’t forget to set the <a class="reference internal" href="../settings.html#std:setting-STATICFILES_DIRS"><tt class="xref std std-setting docutils literal"><span class="pre">STATICFILES_DIRS</span></tt></a> setting appropriately to let <tt class="docutils literal"><span class="pre">django.contrib.staticfiles</span></tt> know where to look for files in addition to files in app directories.</p> <div class="admonition warning"> <p class="first admonition-title">Warning</p> <p>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> <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> </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></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.6.7 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">Sep 26, 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>