django/docs/howto/static-files/index.txt

===================================
Managing static files (CSS, images)
===================================

Websites generally need to serve additional files such as images, JavaScript,
or CSS. In Django, we refer to these files as "static files".  Django provides
:mod:`django.contrib.staticfiles` to help you manage them.

This page describes how you can serve these static files.

Configuring static files
========================

1. Make sure that ``django.contrib.staticfiles`` is included in your
   :setting:`INSTALLED_APPS`.

2. In your settings file, define :setting:`STATIC_URL`, for example::

      STATIC_URL = '/static/'

3. In your templates, either hardcode the url like
   ``/static/my_app/myexample.jpg`` or, preferably, use the
   :ttag:`static<staticfiles-static>` template tag to build the URL for the given
   relative path by using the configured :setting:`STATICFILES_STORAGE` storage
   (this makes it much easier when you want to switch to a content delivery
   network (CDN) for serving static files).

   .. _staticfiles-in-templates:

   .. code-block:: html+django

        {% load staticfiles %}
        <img src="{% static "my_app/myexample.jpg" %}" alt="My image"/>

4. Store your static files in a folder called ``static`` in your app. For
   example ``my_app/static/my_app/myimage.jpg``.

.. admonition:: Serving the files

    In addition to these configuration steps, you'll also need to actually
    serve the static files.

    During development, this will be done automatically if you use
    :djadmin:`runserver` and :setting:`DEBUG` is set to ``True`` (see
    :func:`django.contrib.staticfiles.views.serve`).

    This method is **grossly inefficient** and probably **insecure**,
    so it is **unsuitable for production**.

    See :doc:`/howto/static-files/deployment` for proper strategies to serve
    static files in production environments.

Your project will probably also have static assets that aren't tied to a
particular app. In addition to using a ``static/`` directory inside your apps,
you can define a list of directories (:setting:`STATICFILES_DIRS`) in your
settings file where Django will also look for static files. For example::

    STATICFILES_DIRS = (
        os.path.join(BASE_DIR, "static"),
        '/var/www/static/',
    )

See the documentation for the :setting:`STATICFILES_FINDERS` setting for
details on how ``staticfiles`` finds your files.

.. admonition:: Static file namespacing

    Now we *might* be able to get away with putting our static files directly
    in ``my_app/static/`` (rather than creating another ``my_app``
    subdirectory), but it would actually be a bad idea. Django will use the
    first static file it finds whose name matches, and if you had a static file
    with the same name in a *different* application, Django would be unable to
    distinguish between them. We need to be able to point Django at the right
    one, and the easiest way to ensure this is by *namespacing* them. That is,
    by putting those static files inside *another* directory named for the
    application itself.


Serving files uploaded by a user
================================

During development, you can serve user-uploaded media files from
:setting:`MEDIA_ROOT` using the :func:`django.contrib.staticfiles.views.serve`
view. This is not suitable for production use! For some common deployment
strategies, see :doc:`/howto/static-files/deployment`.

For example, if your :setting:`MEDIA_URL` is defined as '/media/', you can do
this by adding the following snippet to your urls.py::

    from django.conf import settings
    from django.conf.urls.static import static

    urlpatterns = patterns('',
        # ... the rest of your URLconf goes here ...
    ) + static(settings.MEDIA_URL, document_root=settings.MEDIA_ROOT)

.. note::

    This helper function works only in debug mode and only if
    the given prefix is local (e.g. ``/static/``) and not a URL (e.g.
    ``http://static.example.com/``).

Deployment
==========

:mod:`django.contrib.staticfiles` provides a convenience management command
for gathering static files in a single directory so you can serve them easily.

1. Set the :setting:`STATIC_ROOT` setting to the directory from which you'd
   like to serve these files, for example::

       STATIC_ROOT = "/var/www/example.com/static/"

2. Run the :djadmin:`collectstatic` management command::

       ./manage.py collectstatic

   This will copy all files from your static folders into the
   :setting:`STATIC_ROOT` directory.

3. Use a web server of your choice to serve the
   files. :doc:`/howto/static-files/deployment` covers some common deployment
   strategies for static files.

Learn more
==========

This document has covered the basics and some common usage patterns. For
complete details on all the settings, commands, template tags, and other pieces
included in :mod:`django.contrib.staticfiles`, see :doc:`the staticfiles
reference </ref/contrib/staticfiles>`.