ServeStatic

ServeStatic simplifies static file serving with minimal lines of configuration. It enables you to create a self-contained unit without requiring external services like Nginx or Amazon S3. This can simplify any production deployment, but is especially useful for platforms like Heroku, OpenShift, and other PaaS providers.

This project is designed to work seamlessly with CDNs to ensure high performance for traffic-intensive sites. It can be run in "standalone" mode, or alongside any preexisting ASGI/WSGI app. A command-line interface is provided to perform common tasks such as multi-format compression, file-name hashing, and manifest generation. Extra features and auto-configuration are available for Django users.

When using ServeStatic, best practices are automatically handled such as:

• Automatically serving compressed content
• Proper handling of Accept-Encoding and Vary headers
• Setting far-future cache headers for immutable static files.

Quick Start

Here is a short example of ASGI standalone mode:

# filename: my_project.py
from servestatic import ServeStaticASGI

asgi_app = ServeStaticASGI(
    application=None,  # `application=None` will run ServeStatic in standalone mode.
    root="/path/to/static/files",
)

Now, use any webserver CLI to serve static files. Since this example uses ASGI, here is a sample command for uvicorn (a popular ASGI webserver):

uvicorn my_project:asgi_app

Visit the documentation to get started, or learn more about ServeStatic .

Frequently Asked Questions

Isn't serving static files from Python horribly inefficient?

The short answer to this is that if you care about performance and efficiency then you should be using ServeStatic behind a CDN (such as CloudFront). Due to the caching headers ServeStatic sends, the vast majority of static requests will be served directly by the CDN without touching your application, so it really doesn't make much difference how efficient ServeStatic is.

That said, ServeStatic is pretty efficient. Because it only has to serve a fixed set of files it does all the work of finding files and determining the correct headers upfront on initialization. Requests can then be served with little more than a dictionary lookup to find the appropriate response. Also, when used with a file_wrapper compatible WSGI server (e.g. gunicorn) or zerocopysend/pathsend compatible ASGI server (e.g. granian, anycorn, nonecorn) the actual business of pushing the file down the network interface is handled by the kernel's very efficient sendfile syscall, not by Python.

Shouldn't I be pushing my static files to S3 (using Django-Storages)?

A push-based approach adds complexity and fragility to your deployment process: extra libraries specific to your storage backend, extra configuration and authentication keys, and extra tasks that must be run at specific points in the deployment in order for everything to work. With the CDN-as-caching-proxy approach that ServeStatic takes there are just two bits of configuration: the URL of the CDN, and the URL of your application. Everything else is just standard HTTP semantics. This makes your deployments simpler, your life easier, and you happier.

What's the point in ServeStatic when I can use apache/nginx?

There are two answers here. One is that ServeStatic is designed to work in situations where apache, nginx, and the like aren't easily available. But more importantly, it's easy to underestimate what's involved in serving static files correctly. Does your few lines of nginx configuration distinguish which files which will never change and set the cache headers appropriately? Did you add the right CORS headers so that your fonts load correctly when served via a CDN? Did you turn on the special nginx setting which allows it to send gzip content in response to an HTTP/1.0 request? Did you install, enable, and configure support for zstd and brotli compression?

None of this is rocket science, but it's fiddly and annoying and ServeStatic takes care of all it for you.

This project is a fork of WhiteNoise for ASGI support, bug fixes, security updates, new features, and performance upgrades.