CLI Reference¶
ServeStatic comes with a handy command line utility for common static file operations: manifest generation, compression, minification, and hashing.
You can either run this during development and commit your generated/compressed files to your repository, or you can run this as part of your build and deploy processes.
Note
This CLI is intended for non-Django deployments. For Django users, these features are handled automatically within Django's collectstatic command when using ServeStatic's CompressedManifestStaticFilesStorage storage backend.
Usage¶
$ servestatic --help
usage: servestatic [-h] [--all] [--hash] [--manifest] [--compress] [--clear]
[--merge-manifest] [--copy-original] [--no-gzip]
[--no-brotli] [--no-zstd] [--minify]
[--zstd-dict ZSTD_DICT] [--zstd-dict-raw]
[--zstd-level ZSTD_LEVEL] [-q] [-e EXCLUDE]
src dest
Process static files: copy, optionally hash, and compress.
positional arguments:
src Source directory containing static files.
dest Destination directory for processed files.
options:
-h, --help show this help message and exit
--all Perform all operations (equivalent to --hash
--manifest --compress). (default: False)
--hash Generate hashed versions of files. (default: False)
--manifest Generate a manifest file (staticfiles.json). (default:
False)
--compress Generate compressed versions (gzip/zstd/brotli) of
files. (default: False)
--minify Minify CSS and JS files. (default: False)
--clear Empty the destination directory before processing.
(default: False)
--merge-manifest Merge the new manifest with an existing manifest in
the dest directory. Fails if the existing manifest is
not found. (default: False)
--copy-original Copy the original unhashed files into the dest
directory alongside the hashed versions (only applies
with --hash). (default: False)
--no-gzip Don't produce gzip '.gz' files (only applies with
--compress). (default: True)
--no-brotli Don't produce brotli '.br' files (only applies with
--compress). (default: True)
--no-zstd Don't produce zstd '.zstd' files (only applies with
--compress). (default: True)
--zstd-dict ZSTD_DICT
Path to a zstd dictionary file (only applies with
--compress). (default: None)
--zstd-dict-raw Treat the zstd dictionary as raw content (only applies
with --compress). (default: False)
--zstd-level ZSTD_LEVEL
Compression level for zstd output (only applies with
--compress). (default: None)
-q, --quiet Don't produce log output. (default: False)
-e EXCLUDE, --exclude EXCLUDE
Glob pattern(s) to exclude from processing
(compression/hashing). These files are still copied.
(default: None)
Compression Details¶
When ServeStatic builds its list of available files, it optionally checks for corresponding files with .gz, .zstd, and .br suffixes (e.g., scripts/app.js, scripts/app.js.gz, scripts/app.js.zstd, and scripts/app.js.br). If it finds them, it will serve those compressed versions when clients indicate support via Accept-Encoding.
On Python 3.14+, zstd support is built in via the standard library.
On older Python versions, Brotli support is available by installing the Brotli package.
You can also pass a custom zstd dictionary with --zstd-dict and optionally mark it raw with --zstd-dict-raw.
Hash Details¶
This command will output a cache-busting static manifest, which can be used to correlate the original file path to the hashed path.
Every file provided in your directory gets duplicate versions bearing a unique MD5 hash signature of the internal stream state appended inside its extension structure (e.g., test.css -> test.296ab49302a4.css).
It generates a directory-root lookup log file called staticfiles.json detailing out mapping paths, giving simple access for ASGI loaders that inject the resolved filename.
When using --merge-manifest, ServeStatic requires an existing staticfiles.json in dest. It merges the paths mapping and preserves custom top-level keys (for example, metadata keys you add manually).