Managing static files (e.g. images, JavaScript, CSS)Link to this heading#

Configuring static filesLink to this heading#

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

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

   Code

   STATIC_URL = '/static/'
   

3. In your templates, either hardcode the url like /static/my_app/example.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).

   Django template

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

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

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:

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

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

Serving static files during developmentLink to this heading#

If you use django.contrib.staticfiles as explained above, runserver will do this automatically when DEBUG is set to True. If you don’t have django.contrib.staticfiles in INSTALLED_APPS, you can still manually serve static files 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 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 = [
    # ... the rest of your URLconf goes here ...
] + static(settings.STATIC_URL, document_root=settings.STATIC_ROOT)

Serving files uploaded by a user during developmentLink to this heading#

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 urls.py:

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

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

TestingLink to this heading#

When running tests that use actual HTTP requests instead of the built-in testing client (i.e. when using the built-in 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 STATIC_ROOT.

Because of this, staticfiles ships its own django.contrib.staticfiles.testing.StaticLiveServerTestCase, 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 collectstatic first.

DeploymentLink to this heading#

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:

   Code

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

2. Run the collectstatic management command:

   Code

   $ python manage.py collectstatic
   

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

3. Use a web server of your choice to serve the files. Deploying static files covers some common deployment strategies for static files.

Learn moreLink to this heading#

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.