=================================== 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` 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 %} 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, if you use :mod:`django.contrib.staticfiles`, this will be done automatically by :djadmin:`runserver` when :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 static files during development. ======================================== If you use :mod:`django.contrib.staticfiles` as explained above, :djadmin:`runserver` will do this automatically when :setting:`DEBUG` is set to ``True``. If you don't have ``django.contrib.staticfiles`` in :setting:`INSTALLED_APPS`, you can still manually serve static files 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:`STATIC_URL` is defined as ``/static/``, 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.STATIC_URL, document_root=settings.STATIC_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/``). Also this helper function only serves the actual :setting:`STATIC_ROOT` folder; it doesn't perform static files discovery like :mod:`django.contrib.staticfiles`. Serving files uploaded by a user during development. ==================================================== 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. ``/media/``) and not a URL (e.g. ``http://media.example.com/``). .. _staticfiles-testing-support: Testing ======= When running tests that use actual HTTP requests instead of the built-in testing client (i.e. when using the built-in :class:`LiveServerTestCase `) the static assets need to be served along the rest of the content so the test environment reproduces the real one as faithfully as possible, but ``LiveServerTestCase`` has only very basic static file-serving functionality: It doesn't know about the finders feature of the ``staticfiles`` application and assumes the static content has already been collected under :setting:`STATIC_ROOT`. Because of this, ``staticfiles`` ships its own :class:`django.contrib.staticfiles.testing.StaticLiveServerCase`, a subclass of the built-in one that has the ability to transparently serve all the assets during execution of these tests in a way very similar to what we get at development time with ``DEBUG = True``, i.e. without having to collect them using :djadmin:`collectstatic` first. .. versionadded:: 1.7 :class:`django.contrib.staticfiles.testing.StaticLiveServerCase` is new in Django 1.7. Previously its functionality was provided by :class:`django.test.LiveServerTestCase`. 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 `.