Managing static files (e.g. images, JavaScript, CSS)

Websites generally need to serve additional files such as images, JavaScript,or CSS. In Django, we refer to these files as “static files”. Django providesdjango.contrib.staticfiles to help you manage them.

This page describes how you can serve these static files.

Configuring static files

• Make sure that django.contrib.staticfiles is included in yourINSTALLED_APPS.

• In your settings file, define STATIC_URL, for example:

STATIC_URL = '/static/'

• In your templates, use the static template tag to build the URL forthe given relative path using the configured STATICFILES_STORAGE.

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

• Store your static files in a folder called static in your app. Forexample my_app/static/my_app/example.jpg.

Serving the files

In addition to these configuration steps, you’ll also need to actuallyserve the static files.

During development, if you use django.contrib.staticfiles, this willbe done automatically by runserver when DEBUG is setto 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 servestatic files in production environments.

Your project will probably also have static assets that aren’t tied to aparticular app. In addition to using a static/ directory inside your apps,you can define a list of directories (STATICFILES_DIRS) in yoursettings 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 fordetails on how staticfiles finds your files.

Static file namespacing

Now we might be able to get away with putting our static files directlyin myapp/static/ (rather than creating another my_appsubdirectory), but it would actually be a bad idea. Django will use thefirst static file it finds whose name matches, and if you had a static filewith the same name in a _different application, Django would be unable todistinguish between them. We need to be able to point Django at the rightone, and the best way to ensure this is by namespacing them. That is,by putting those static files inside another directory named for theapplication itself.

Serving static files during development

If you use django.contrib.staticfiles as explained above,runserver will do this automatically when DEBUG is setto True. If you don’t have django.contrib.staticfiles inINSTALLED_APPS, you can still manually serve static files using thedjango.views.static.serve() view.

This is not suitable for production use! For some common deploymentstrategies, see Deploying static files.

For example, if your STATIC_URL is defined as /static/, you can dothis 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)

Note

This helper function works only in debug mode and only ifthe 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 STATIC_ROOTfolder; it doesn’t perform static files discovery likedjango.contrib.staticfiles.

Serving files uploaded by a user during development

During development, you can serve user-uploaded media files fromMEDIA_ROOT using the django.views.static.serve() view.

This is not suitable for production use! For some common deploymentstrategies, see Deploying static files.

For example, if your MEDIA_URL is defined as /media/, you can dothis 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)

Note

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

Testing

When running tests that use actual HTTP requests instead of the built-intesting client (i.e. when using the built-in LiveServerTestCase) the static assets need to be served alongthe rest of the content so the test environment reproduces the real one asfaithfully as possible, but LiveServerTestCase has only very basic staticfile-serving functionality: It doesn’t know about the finders feature of thestaticfiles application and assumes the static content has already beencollected under STATIC_ROOT.

Because of this, staticfiles ships its owndjango.contrib.staticfiles.testing.StaticLiveServerTestCase, a subclassof the built-in one that has the ability to transparently serve all the assetsduring execution of these tests in a way very similar to what we get atdevelopment time with DEBUG = True, i.e. without having to collect themusing collectstatic first.

Deployment

django.contrib.staticfiles provides a convenience management commandfor gathering static files in a single directory so you can serve them easily.

• Set the STATIC_ROOT setting to the directory from which you’dlike to serve these files, for example:

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

• Run the collectstatic management command:

$ python manage.py collectstatic

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

• Use a web server of your choice to serve thefiles. Deploying static files covers some common deploymentstrategies for static files.

Learn more

This document has covered the basics and some common usage patterns. Forcomplete details on all the settings, commands, template tags, and other piecesincluded in django.contrib.staticfiles, see the staticfilesreference.