<!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>How to serve static files — Django v1.2 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.2',
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 v1.2 documentation" href="../index.html" />
<link rel="up" title="“How-to” guides" href="index.html" />
<link rel="next" title="Django FAQ" href="../faq/index.html" />
<link rel="prev" title="Outputting PDFs with Django" href="outputting-pdf.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 = "../ref/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 v1.2 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="outputting-pdf.html" title="Outputting PDFs with Django">previous</a>
|
<a href="index.html" title="&#8220;How-to&#8221; guides" accesskey="U">up</a>
|
<a href="../faq/index.html" title="Django FAQ">next</a> »</div>
</div>
<div id="bd">
<div id="yui-main">
<div class="yui-b">
<div class="yui-g" id="howto-static-files">
<div class="section" id="s-module-django.views.static">
<span id="s-how-to-serve-static-files"></span><span id="module-django.views.static"></span><span id="how-to-serve-static-files"></span><h1>How to serve static files<a class="headerlink" href="#module-django.views.static" title="Permalink to this headline">¶</a></h1>
<p>Django itself doesn’t serve static (media) files, such as images, style sheets,
or video. It leaves that job to whichever Web server you choose.</p>
<p>The reasoning here is that standard Web servers, such as <a class="reference external" href="http://httpd.apache.org/">Apache</a>, <a class="reference external" href="http://www.lighttpd.net/">lighttpd</a> and
<a class="reference external" href="http://www.cherokee-project.com/">Cherokee</a>, are much more fine-tuned at serving static files than a Web
application framework.</p>
<p>With that said, Django does support static files <strong>during development</strong>. You can
use the <tt class="xref py py-func docutils literal"><span class="pre">django.views.static.serve()</span></tt> view to serve media files.</p>
<div class="admonition-see-also admonition seealso">
<p class="first admonition-title">See also</p>
<p class="last">If you just need to serve the admin media from a nonstandard location, see
the <a class="reference internal" href="../ref/django-admin.html#django-admin-option---adminmedia"><tt class="xref std std-djadminopt docutils literal"><span class="pre">--adminmedia</span></tt></a> parameter to <a class="reference internal" href="../ref/django-admin.html#django-admin-runserver"><tt class="xref std std-djadmin docutils literal"><span class="pre">runserver</span></tt></a>.</p>
</div>
<div class="section" id="s-the-big-fat-disclaimer">
<span id="the-big-fat-disclaimer"></span><h2>The big, fat disclaimer<a class="headerlink" href="#the-big-fat-disclaimer" title="Permalink to this headline">¶</a></h2>
<p>Using this method is <strong>inefficient</strong> and <strong>insecure</strong>. Do not use this in a
production setting. Use this only for development.</p>
<p>For information on serving static files in an Apache production environment,
see the <a class="reference internal" href="deployment/modpython.html#serving-media-files"><em>Django mod_python documentation</em></a>.</p>
</div>
<div class="section" id="s-how-to-do-it">
<span id="how-to-do-it"></span><h2>How to do it<a class="headerlink" href="#how-to-do-it" title="Permalink to this headline">¶</a></h2>
<p>Here’s the formal definition of the <tt class="xref py py-func docutils literal"><span class="pre">serve()</span></tt> view:</p>
<dl class="function">
<dt>
<tt class="descname">def serve(request, path, document_root, show_indexes=False)</tt></dt>
<dd></dd></dl>
<p>To use it, just put this in your <a class="reference internal" href="../topics/http/urls.html"><em>URLconf</em></a>:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="p">(</span><span class="s">r'^site_media/(?P<path>.*)$'</span><span class="p">,</span> <span class="s">'django.views.static.serve'</span><span class="p">,</span>
<span class="p">{</span><span class="s">'document_root'</span><span class="p">:</span> <span class="s">'/path/to/media'</span><span class="p">}),</span>
</pre></div>
</div>
<p>...where <tt class="docutils literal"><span class="pre">site_media</span></tt> is the URL where your media will be rooted, and
<tt class="docutils literal"><span class="pre">/path/to/media</span></tt> is the filesystem root for your media. This will call the
<tt class="xref py py-func docutils literal"><span class="pre">serve()</span></tt> view, passing in the path from the URLconf
and the (required) <tt class="docutils literal"><span class="pre">document_root</span></tt> parameter.</p>
<p>Given the above URLconf:</p>
<ul class="simple">
<li>The file <tt class="docutils literal"><span class="pre">/path/to/media/foo.jpg</span></tt> will be made available at the URL
<tt class="docutils literal"><span class="pre">/site_media/foo.jpg</span></tt>.</li>
<li>The file <tt class="docutils literal"><span class="pre">/path/to/media/css/mystyles.css</span></tt> will be made available
at the URL <tt class="docutils literal"><span class="pre">/site_media/css/mystyles.css</span></tt>.</li>
<li>The file <tt class="docutils literal"><span class="pre">/path/bar.jpg</span></tt> will not be accessible, because it doesn't
fall under the document root.</li>
</ul>
<p>Of course, it's not compulsory to use a fixed string for the
<tt class="docutils literal"><span class="pre">'document_root'</span></tt> value. You might wish to make that an entry in your
settings file and use the setting value there. That will allow you and
other developers working on the code to easily change the value as
required. For example, if we have a line in <tt class="docutils literal"><span class="pre">settings.py</span></tt> that says:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">STATIC_DOC_ROOT</span> <span class="o">=</span> <span class="s">'/path/to/media'</span>
</pre></div>
</div>
<p>...we could write the above <a class="reference internal" href="../topics/http/urls.html"><em>URLconf</em></a> entry as:</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="o">...</span>
<span class="p">(</span><span class="s">r'^site_media/(?P<path>.*)$'</span><span class="p">,</span> <span class="s">'django.views.static.serve'</span><span class="p">,</span>
<span class="p">{</span><span class="s">'document_root'</span><span class="p">:</span> <span class="n">settings</span><span class="o">.</span><span class="n">STATIC_DOC_ROOT</span><span class="p">}),</span>
</pre></div>
</div>
<p>Be careful not to use the same path as your <a class="reference internal" href="../ref/settings.html#std:setting-ADMIN_MEDIA_PREFIX"><tt class="xref std std-setting docutils literal"><span class="pre">ADMIN_MEDIA_PREFIX</span></tt></a> (which defaults
to <tt class="docutils literal"><span class="pre">/media/</span></tt>) as this will overwrite your URLconf entry.</p>
</div>
<div class="section" id="s-directory-listings">
<span id="directory-listings"></span><h2>Directory listings<a class="headerlink" href="#directory-listings" title="Permalink to this headline">¶</a></h2>
<p>Optionally, you can pass the <tt class="docutils literal"><span class="pre">show_indexes</span></tt> parameter to the
<tt class="xref py py-func docutils literal"><span class="pre">serve()</span></tt> view. This is <tt class="xref docutils literal"><span class="pre">False</span></tt> by default. If it's
<tt class="xref docutils literal"><span class="pre">True</span></tt>, Django will display file listings for directories.</p>
<p>For example:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="p">(</span><span class="s">r'^site_media/(?P<path>.*)$'</span><span class="p">,</span> <span class="s">'django.views.static.serve'</span><span class="p">,</span>
<span class="p">{</span><span class="s">'document_root'</span><span class="p">:</span> <span class="s">'/path/to/media'</span><span class="p">,</span> <span class="s">'show_indexes'</span><span class="p">:</span> <span class="bp">True</span><span class="p">}),</span>
</pre></div>
</div>
<p>You can customize the index view by creating a template called
<tt class="docutils literal"><span class="pre">static/directory_index.html</span></tt>. That template gets two objects in its context:</p>
<ul class="simple">
<li><tt class="docutils literal"><span class="pre">directory</span></tt> -- the directory name (a string)</li>
<li><tt class="docutils literal"><span class="pre">file_list</span></tt> -- a list of file names (as strings) in the directory</li>
</ul>
<p>Here's the default <tt class="docutils literal"><span class="pre">static/directory_index.html</span></tt> template:</p>
<div class="highlight-html+django"><div class="highlight"><pre><span class="cp"><!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"></span>
<span class="nt"><html</span> <span class="na">xmlns=</span><span class="s">"http://www.w3.org/1999/xhtml"</span> <span class="na">xml:lang=</span><span class="s">"en"</span> <span class="na">lang=</span><span class="s">"en"</span><span class="nt">></span>
<span class="nt"><head></span>
<span class="nt"><meta</span> <span class="na">http-equiv=</span><span class="s">"Content-type"</span> <span class="na">content=</span><span class="s">"text/html; charset=utf-8"</span> <span class="nt">/></span>
<span class="nt"><meta</span> <span class="na">http-equiv=</span><span class="s">"Content-Language"</span> <span class="na">content=</span><span class="s">"en-us"</span> <span class="nt">/></span>
<span class="nt"><meta</span> <span class="na">name=</span><span class="s">"robots"</span> <span class="na">content=</span><span class="s">"NONE,NOARCHIVE"</span> <span class="nt">/></span>
<span class="nt"><title></span>Index of <span class="cp">{{</span> <span class="nv">directory</span> <span class="cp">}}</span><span class="nt"></title></span>
<span class="nt"></head></span>
<span class="nt"><body></span>
<span class="nt"><h1></span>Index of <span class="cp">{{</span> <span class="nv">directory</span> <span class="cp">}}</span><span class="nt"></h1></span>
<span class="nt"><ul></span>
<span class="cp">{%</span> <span class="k">for</span> <span class="nv">f</span> <span class="k">in</span> <span class="nv">file_list</span> <span class="cp">%}</span>
<span class="nt"><li><a</span> <span class="na">href=</span><span class="s">"</span><span class="cp">{{</span> <span class="nv">f</span> <span class="cp">}}</span><span class="s">"</span><span class="nt">></span><span class="cp">{{</span> <span class="nv">f</span> <span class="cp">}}</span><span class="nt"></a></li></span>
<span class="cp">{%</span> <span class="k">endfor</span> <span class="cp">%}</span>
<span class="nt"></ul></span>
<span class="nt"></body></span>
<span class="nt"></html></span>
</pre></div>
</div>
<div class="versionchanged">
<span class="title">Changed in Django 1.0.3:</span> Prior to Django 1.0.3, there was a bug in the view that provided directory
listings. The template that was loaded had to be called
<tt class="docutils literal"><span class="pre">static/directory_listing</span></tt> (with no <tt class="docutils literal"><span class="pre">.html</span></tt> extension). For backwards
compatibility with earlier versions, Django will still load templates with
the older (no extension) name, but it will prefer the
<tt class="docutils literal"><span class="pre">directory_index.html</span></tt> version.</div>
</div>
<div class="section" id="s-limiting-use-to-debug-true">
<span id="limiting-use-to-debug-true"></span><h2>Limiting use to DEBUG=True<a class="headerlink" href="#limiting-use-to-debug-true" title="Permalink to this headline">¶</a></h2>
<p>Because URLconfs are just plain Python modules, you can use Python logic to
make the static-media view available only in development mode. This is a handy
trick to make sure the static-serving view doesn't slip into a production
setting by mistake.</p>
<p>Do this by wrapping an <tt class="docutils literal"><span class="pre">if</span> <span class="pre">DEBUG</span></tt> statement around the
<tt class="xref py py-func docutils literal"><span class="pre">django.views.static.serve()</span></tt> inclusion. Here's a full example URLconf:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">django.conf.urls.defaults</span> <span class="kn">import</span> <span class="o">*</span>
<span class="kn">from</span> <span class="nn">django.conf</span> <span class="kn">import</span> <span class="n">settings</span>
<span class="n">urlpatterns</span> <span class="o">=</span> <span class="n">patterns</span><span class="p">(</span><span class="s">''</span><span class="p">,</span>
<span class="p">(</span><span class="s">r'^articles/2003/$'</span><span class="p">,</span> <span class="s">'news.views.special_case_2003'</span><span class="p">),</span>
<span class="p">(</span><span class="s">r'^articles/(?P<year>\d{4})/$'</span><span class="p">,</span> <span class="s">'news.views.year_archive'</span><span class="p">),</span>
<span class="p">(</span><span class="s">r'^articles/(?P<year>\d{4})/(?P<month>\d{2})/$'</span><span class="p">,</span> <span class="s">'news.views.month_archive'</span><span class="p">),</span>
<span class="p">(</span><span class="s">r'^articles/(?P<year>\d{4})/(?P<month>\d{2})/(?P<day>\d+)/$'</span><span class="p">,</span> <span class="s">'news.views.article_detail'</span><span class="p">),</span>
<span class="p">)</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">''</span><span class="p">,</span>
<span class="p">(</span><span class="s">r'^site_media/(?P<path>.*)$'</span><span class="p">,</span> <span class="s">'django.views.static.serve'</span><span class="p">,</span> <span class="p">{</span><span class="s">'document_root'</span><span class="p">:</span> <span class="s">'/path/to/media'</span><span class="p">}),</span>
<span class="p">)</span>
</pre></div>
</div>
<p>This code is straightforward. It imports the settings and checks the value of
the <a class="reference internal" href="../ref/settings.html#std:setting-DEBUG"><tt class="xref std std-setting docutils literal"><span class="pre">DEBUG</span></tt></a> setting. If it evaluates to <tt class="xref docutils literal"><span class="pre">True</span></tt>, then <tt class="docutils literal"><span class="pre">site_media</span></tt>
will be associated with the <tt class="docutils literal"><span class="pre">django.views.static.serve</span></tt> view. If not, then the
view won't be made available.</p>
<p>Of course, the catch here is that you'll have to remember to set <tt class="docutils literal"><span class="pre">DEBUG=False</span></tt>
in your production settings file. But you should be doing that anyway.</p>
</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="#">How to serve static files</a><ul>
<li><a class="reference internal" href="#the-big-fat-disclaimer">The big, fat disclaimer</a></li>
<li><a class="reference internal" href="#how-to-do-it">How to do it</a></li>
<li><a class="reference internal" href="#directory-listings">Directory listings</a></li>
<li><a class="reference internal" href="#limiting-use-to-debug-true">Limiting use to DEBUG=True</a></li>
</ul>
</li>
</ul>
<h3>Browse</h3>
<ul>
<li>Prev: <a href="outputting-pdf.html">Outputting PDFs with Django</a></li>
<li>Next: <a href="../faq/index.html">Django FAQ</a></li>
</ul>
<h3>You are here:</h3>
<ul>
<li>
<a href="../index.html">Django v1.2 documentation</a>
<ul><li><a href="index.html">“How-to” guides</a>
<ul><li>How to serve static files</li></ul>
</li></ul>
</li>
</ul>
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../_sources/howto/static-files.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" size="18" />
<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">Oct 20, 2010</p>
</div>
</div>
<div id="ft">
<div class="nav">
« <a href="outputting-pdf.html" title="Outputting PDFs with Django">previous</a>
|
<a href="index.html" title="&#8220;How-to&#8221; guides" accesskey="U">up</a>
|
<a href="../faq/index.html" title="Django FAQ">next</a> »</div>
</div>
</div>
<div class="clearer"></div>
</div>
</body>
</html>
distrib
>
Arklinux
>
devel
>
i586
>
media
>
main
>
by-pkgid
>
5fcb1fedf34660bc240dc59b7bfcebc4
>
files
>
289
