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 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 INSTALLED_APPS.

  2. In your settings file, define 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 static template tag to build the URL for the given relative path by using the configured STATICFILES_STORAGE storage (this makes it much easier when you want to switch to a content delivery network (CDN) for serving static files).

    {% 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.

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 runserver and DEBUG is set to True (see django.contrib.staticfiles.views.serve()).

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

See Deploying static files 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 (STATICFILES_DIRS) in your settings file where Django will also look for static files. For example:

    os.path.join(BASE_DIR, "static"),

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

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 MEDIA_ROOT using the django.contrib.staticfiles.views.serve() view. This is not suitable for production use! For some common deployment strategies, see Deploying static files.

For example, if your MEDIA_URL is defined as ‘/media/’, you can do this by adding the following snippet to your

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)


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.


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 STATIC_ROOT setting to the directory from which you’d like to serve these files, for example:

    STATIC_ROOT = "/var/www/"
  2. Run the collectstatic management command:

    ./ collectstatic

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

  3. Use a webserver of your choice to serve the files. Deploying static files 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 django.contrib.staticfiles, see the staticfiles reference.