ServeStatic

4.3.0 verified Sat May 09 auth: no python

Production-grade static file server for Python WSGI & ASGI applications, with support for Django, compression, and content hashing. Current version: 4.3.0, released April 2025. Active development.

pip install servestatic

Common errors

error ModuleNotFoundError: No module named 'servestatic' ↓

cause Library not installed or installed in wrong environment.

fix

Run pip install servestatic in the correct Python environment.

error ImportError: cannot import name 'ServeStatic' from 'servestatic' ↓

cause Importing from wrong module; ServeStatic class is in servestatic.wsgi.

fix

Use from servestatic.wsgi import ServeStatic or from servestatic.asgi import ServeStaticASGI for ASGI.

error TypeError: ServeStatic() missing 1 required positional argument: 'application' ↓

cause First argument to ServeStatic must be a WSGI app.

fix

Wrap your existing WSGI app: app.wsgi_app = ServeStatic(app.wsgi_app, root='...').

error django.core.exceptions.ImproperlyConfigured: The SERVESTATIC setting is not configured ↓

cause Django integration requires adding 'servestatic' to INSTALLED_APPS.

fix

Add 'servestatic' to INSTALLED_APPS in Django settings.

Warnings

breaking In version 4.0.0, default immutable_file_test regex changed to match files hashed by servestatic --hash. Custom file patterns may no longer be treated as immutable. ↓

fix Set immutable_file_test explicitly if you rely on old behavior, e.g., ServeStatic(app, immutable_file_test=r'').

breaking In version 4.1.0, symlink following is now disabled by default for security. If your static directory uses symlinks, you must set allow_unsafe_symlinks=True. ↓

fix Pass allow_unsafe_symlinks=True to ServeStatic or set SERVESTATIC_ALLOW_UNSAFE_SYMLINKS=True in Django settings.

deprecated The compression API via python -m servestatic.compress is deprecated as of 4.0.0. Use servestatic --compress CLI instead. ↓

fix Run `servestatic --compress` after installing with [cli] extras.

gotcha When using Django, SERVESTATIC_USE_STATIC_ROOT (added in 4.2.0) is off by default. If you rely on collectstatic to populate STATIC_ROOT, serve from STATIC_ROOT directly only if you enable this setting. ↓

fix Set SERVESTATIC_USE_STATIC_ROOT = True in settings.py if you want ServeStatic to scan STATIC_ROOT at startup.

Install

pip install servestatic[cli]

Imports

ServeStatic

wrong

from servestatic import ServeStatic

correct

from servestatic.wsgi import ServeStatic

WSGI class is in servestatic.wsgi, not top-level.

ServeStaticASGI

wrong

from servestatic import ServeStaticASGI

correct

from servestatic.asgi import ServeStaticASGI

ASGI class is in servestatic.asgi.

Quickstart

Wrap any WSGI app with ServeStatic to serve static files.

from servestatic.wsgi import ServeStatic
from flask import Flask, send_from_directory
import os

app = Flask(__name__)
app.wsgi_app = ServeStatic(app.wsgi_app, root='/path/to/static')

@app.route('/')
def index():
    return send_from_directory('/path/to/static', 'index.html')

if __name__ == '__main__':
    app.run()