| 1 |
========================================================= |
| 2 |
How to manage static files (e.g. images, JavaScript, CSS) |
| 3 |
========================================================= |
| 4 |
|
| 5 |
Websites generally need to serve additional files such as images, JavaScript, |
| 6 |
or CSS. In Django, we refer to these files as "static files". Django provides |
| 7 |
:mod:`django.contrib.staticfiles` to help you manage them. |
| 8 |
|
| 9 |
This page describes how you can serve these static files. |
| 10 |
|
| 11 |
Configuring static files |
| 12 |
======================== |
| 13 |
|
| 14 |
#. Make sure that ``django.contrib.staticfiles`` is included in your |
| 15 |
:setting:`INSTALLED_APPS`. |
| 16 |
|
| 17 |
#. In your settings file, define :setting:`STATIC_URL`, for example:: |
| 18 |
|
| 19 |
STATIC_URL = "static/" |
| 20 |
|
| 21 |
#. In your templates, use the :ttag:`static` template tag to build the URL for |
| 22 |
the given relative path using the configured ``staticfiles`` |
| 23 |
:setting:`STORAGES` alias. |
| 24 |
|
| 25 |
.. _staticfiles-in-templates: |
| 26 |
|
| 27 |
.. code-block:: html+django |
| 28 |
|
| 29 |
{% load static %} |
| 30 |
<img src="{% static 'my_app/example.jpg' %}" alt="My image"> |
| 31 |
|
| 32 |
#. Store your static files in a folder called ``static`` in your app. For |
| 33 |
example ``my_app/static/my_app/example.jpg``. |
| 34 |
|
| 35 |
.. admonition:: Serving the files |
| 36 |
|
| 37 |
In addition to these configuration steps, you'll also need to actually |
| 38 |
serve the static files. |
| 39 |
|
| 40 |
During development, if you use :mod:`django.contrib.staticfiles`, this will |
| 41 |
be done automatically by :djadmin:`runserver` when :setting:`DEBUG` is set |
| 42 |
to ``True`` (see :func:`django.contrib.staticfiles.views.serve`). |
| 43 |
|
| 44 |
This method is **grossly inefficient** and probably **insecure**, |
| 45 |
so it is **unsuitable for production**. |
| 46 |
|
| 47 |
See :doc:`/howto/static-files/deployment` for proper strategies to serve |
| 48 |
static files in production environments. |
| 49 |
|
| 50 |
Your project will probably also have static assets that aren't tied to a |
| 51 |
particular app. In addition to using a ``static/`` directory inside your apps, |
| 52 |
you can define a list of directories (:setting:`STATICFILES_DIRS`) in your |
| 53 |
settings file where Django will also look for static files. For example:: |
| 54 |
|
| 55 |
STATICFILES_DIRS = [ |
| 56 |
BASE_DIR / "static", |
| 57 |
"/var/www/static/", |
| 58 |
] |
| 59 |
|
| 60 |
See the documentation for the :setting:`STATICFILES_FINDERS` setting for |
| 61 |
details on how ``staticfiles`` finds your files. |
| 62 |
|
| 63 |
.. admonition:: Static file namespacing |
| 64 |
|
| 65 |
Now we *might* be able to get away with putting our static files directly |
| 66 |
in ``my_app/static/`` (rather than creating another ``my_app`` |
| 67 |
subdirectory), but it would actually be a bad idea. Django will use the |
| 68 |
first static file it finds whose name matches, and if you had a static file |
| 69 |
with the same name in a *different* application, Django would be unable to |
| 70 |
distinguish between them. We need to be able to point Django at the right |
| 71 |
one, and the best way to ensure this is by *namespacing* them. That is, |
| 72 |
by putting those static files inside *another* directory named for the |
| 73 |
application itself. |
| 74 |
|
| 75 |
You can namespace static assets in :setting:`STATICFILES_DIRS` by |
| 76 |
specifying :ref:`prefixes <staticfiles-dirs-prefixes>`. |
| 77 |
|
| 78 |
.. _serving-static-files-in-development: |
| 79 |
|
| 80 |
Serving static files during development |
| 81 |
======================================= |
| 82 |
|
| 83 |
If you use :mod:`django.contrib.staticfiles` as explained above, |
| 84 |
:djadmin:`runserver` will do this automatically when :setting:`DEBUG` is set |
| 85 |
to ``True``. If you don't have ``django.contrib.staticfiles`` in |
| 86 |
:setting:`INSTALLED_APPS`, you can still manually serve static files using the |
| 87 |
:func:`django.views.static.serve` view. |
| 88 |
|
| 89 |
This is not suitable for production use! For some common deployment |
| 90 |
strategies, see :doc:`/howto/static-files/deployment`. |
| 91 |
|
| 92 |
For example, if your :setting:`STATIC_URL` is defined as ``static/``, you can |
| 93 |
do this by adding the following snippet to your ``urls.py``:: |
| 94 |
|
| 95 |
from django.conf import settings |
| 96 |
from django.conf.urls.static import static |
| 97 |
|
| 98 |
urlpatterns = [ |
| 99 |
# ... the rest of your URLconf goes here ... |
| 100 |
] + static(settings.STATIC_URL, document_root=settings.STATIC_ROOT) |
| 101 |
|
| 102 |
.. note:: |
| 103 |
|
| 104 |
This helper function works only in debug mode and only if |
| 105 |
the given prefix is local (e.g. ``static/``) and not a URL (e.g. |
| 106 |
``http://static.example.com/``). |
| 107 |
|
| 108 |
Also this helper function only serves the actual :setting:`STATIC_ROOT` |
| 109 |
folder; it doesn't perform static files discovery like |
| 110 |
:mod:`django.contrib.staticfiles`. |
| 111 |
|
| 112 |
Finally, static files are served via a wrapper at the WSGI application |
| 113 |
layer. As a consequence, static files requests do not pass through the |
| 114 |
normal :doc:`middleware chain </topics/http/middleware>`. |
| 115 |
|
| 116 |
.. _serving-uploaded-files-in-development: |
| 117 |
|
| 118 |
Serving files uploaded by a user during development |
| 119 |
=================================================== |
| 120 |
|
| 121 |
During development, you can serve user-uploaded media files from |
| 122 |
:setting:`MEDIA_ROOT` using the :func:`django.views.static.serve` view. |
| 123 |
|
| 124 |
This is not suitable for production use! For some common deployment |
| 125 |
strategies, see :doc:`/howto/static-files/deployment`. |
| 126 |
|
| 127 |
For example, if your :setting:`MEDIA_URL` is defined as ``media/``, you can do |
| 128 |
this by adding the following snippet to your :setting:`ROOT_URLCONF`:: |
| 129 |
|
| 130 |
from django.conf import settings |
| 131 |
from django.conf.urls.static import static |
| 132 |
|
| 133 |
urlpatterns = [ |
| 134 |
# ... the rest of your URLconf goes here ... |
| 135 |
] + static(settings.MEDIA_URL, document_root=settings.MEDIA_ROOT) |
| 136 |
|
| 137 |
.. note:: |
| 138 |
|
| 139 |
This helper function works only in debug mode and only if |
| 140 |
the given prefix is local (e.g. ``media/``) and not a URL (e.g. |
| 141 |
``http://media.example.com/``). |
| 142 |
|
| 143 |
.. _staticfiles-testing-support: |
| 144 |
|
| 145 |
Testing |
| 146 |
======= |
| 147 |
|
| 148 |
When running tests that use actual HTTP requests instead of the built-in |
| 149 |
testing client (i.e. when using the built-in :class:`LiveServerTestCase |
| 150 |
<django.test.LiveServerTestCase>`) the static assets need to be served along |
| 151 |
the rest of the content so the test environment reproduces the real one as |
| 152 |
faithfully as possible, but ``LiveServerTestCase`` has only very basic static |
| 153 |
file-serving functionality: It doesn't know about the finders feature of the |
| 154 |
``staticfiles`` application and assumes the static content has already been |
| 155 |
collected under :setting:`STATIC_ROOT`. |
| 156 |
|
| 157 |
Because of this, ``staticfiles`` ships its own |
| 158 |
:class:`django.contrib.staticfiles.testing.StaticLiveServerTestCase`, a subclass |
| 159 |
of the built-in one that has the ability to transparently serve all the assets |
| 160 |
during execution of these tests in a way very similar to what we get at |
| 161 |
development time with ``DEBUG = True``, i.e. without having to collect them |
| 162 |
using :djadmin:`collectstatic` first. |
| 163 |
|
| 164 |
Deployment |
| 165 |
========== |
| 166 |
|
| 167 |
:mod:`django.contrib.staticfiles` provides a convenience management command |
| 168 |
for gathering static files in a single directory so you can serve them easily. |
| 169 |
|
| 170 |
#. Set the :setting:`STATIC_ROOT` setting to the directory from which you'd |
| 171 |
like to serve these files, for example:: |
| 172 |
|
| 173 |
STATIC_ROOT = "/var/www/example.com/static/" |
| 174 |
|
| 175 |
#. Run the :djadmin:`collectstatic` management command: |
| 176 |
|
| 177 |
.. code-block:: shell |
| 178 |
|
| 179 |
$ python manage.py collectstatic |
| 180 |
|
| 181 |
This will copy all files from your static folders into the |
| 182 |
:setting:`STATIC_ROOT` directory. |
| 183 |
|
| 184 |
#. Use a web server of your choice to serve the |
| 185 |
files. :doc:`/howto/static-files/deployment` covers some common deployment |
| 186 |
strategies for static files. |
| 187 |
|
| 188 |
Learn more |
| 189 |
========== |
| 190 |
|
| 191 |
This document has covered the basics and some common usage patterns. For |
| 192 |
complete details on all the settings, commands, template tags, and other pieces |
| 193 |
included in :mod:`django.contrib.staticfiles`, see :doc:`the staticfiles |
| 194 |
reference </ref/contrib/staticfiles>`. |