Skip to content

Serving static files

This page covers:

  • How to serve static files.
  • Options for static files.
  • Non-obvious features handled when serving static files.
  • How to serve a Single Page Application (SPA) that uses the HTML5 History API

To serve static files, use the method app.serve_files as in the following example:

from blacksheep import Application

app = Application()

# serve files contained in a "static" folder relative to the server cwd

The path can be a relative one compared to the application cwd, or an absolute path.

When serving files this way, a match-all route ("*") is configured in the application router for GET and HEAD, and files are read from the configured folder upon web requests.

It is also possible to serve static files from sub-folders:


Enable file discovery (in such case, requests for directories will generate an HTML response with a list of files):

app.serve_files("app/static", discovery=True)

BlackSheep also supports serving static files from multiple folders, and specifying a prefix for the route path:

app = Application()

# serve files contained in a "static" folder relative to the server cwd
app.serve_files("app/images", root_path="images")
app.serve_files("app/videos", root_path="videos")

File extensions

Only files with configured extension are served to the client. By default, only files with these extensions are served (case insensitive check):


To configure extensions, use the dedicated parameter:

app.serve_files("static", extensions={'.foo', '.config'})

Accept-Ranges and Range requests

Range requests are enabled and handled by default (since version 0.2.1), meaning that BlackSheep supports serving big files with pause and resume feature, and serving videos with the possibility to jump to specific points.

ETag and If-None-Match

ETag, If-None-Match and HTTP Status 304 Not Modified are handled automatically, as well as support for HEAD requests returning only headers with information about the files.

Configurable Cache-Control

To control Cache-Control max-age HTTP header, use cache_time parameter (defaults to 10800 seconds).

app.serve_files("static", cache_time=90000)

How to serve SPAs that use HTML5 History API

To serve an SPA that uses HTML5 History API, configure files serving with a fallback_document="index.html" if the index file is called "index.html" (like it happens in most scenarios).

from blacksheep import Application

app = Application()


If the SPA uses a file with a different name, specify both index file name and fallback document to be the same:

from blacksheep import Application

app = Application()


Last modified on: 2022-02-16 07:52:42