Static files#

To serve static files (i.e., serve arbitrary files from a given directory), the create_static_files_router() can be used to create a Router to handle this task.

Serving static files using create_static_files_router#

from pathlib import Path

from litestar import Litestar
from litestar.static_files import create_static_files_router

ASSETS_DIR = Path("assets")


def on_startup():
    ASSETS_DIR.mkdir(exist_ok=True)
    ASSETS_DIR.joinpath("hello.txt").write_text("Hello, world!")


app = Litestar(
    route_handlers=[
        create_static_files_router(path="/static", directories=["assets"]),
    ],
    on_startup=[on_startup],
)

Run it

> curl http://127.0.0.1:8000/static/hello.txt
Hello, world!

In this example, files from the directory assets will be served on the path /static. A file assets/hello.txt would now be available on /static/hello.txt

Attention

Directories are interpreted as relative to the working directory from which the application is started

Sending files as attachments#

By default, files are sent “inline”, meaning they will have a Content-Disposition: inline header.

Setting send_as_attachment to True will send them with a Content-Disposition: attachment instead:

Sending files as attachments using the the send_as_attachment parameter of create_static_files_router()#

from litestar import Litestar
from litestar.static_files import create_static_files_router

app = Litestar(
    route_handlers=[
        create_static_files_router(
            path="/static",
            directories=["assets"],
            send_as_attachment=True,
        )
    ]
)

HTML mode#

“HTML mode” can be enabled by setting html_mode to True.

This will:

Serve and /index.html when the path / is requested
Attempt to serve /404.html when a requested file is not found

Serving HTML files using the html_mode parameter of create_static_files_router()#

from pathlib import Path

from litestar import Litestar
from litestar.static_files import create_static_files_router

HTML_DIR = Path("html")


def on_startup() -> None:
    HTML_DIR.mkdir(exist_ok=True)
    HTML_DIR.joinpath("index.html").write_text("<strong>Hello, world!</strong>")
    HTML_DIR.joinpath("404.html").write_text("<h1>Not found</h1>")


app = Litestar(
    route_handlers=[
        create_static_files_router(
            path="/",
            directories=["html"],
            html_mode=True,
        )
    ],
    on_startup=[on_startup],
)

Run it

> curl http://127.0.0.1:8000/
<strong>Hello, world!</strong>
> curl http://127.0.0.1:8000/index.html
<strong>Hello, world!</strong>
> curl http://127.0.0.1:8000/something
<h1>Not found</h1>

Passing options to the generated router#

Options available on Router can be passed to directly create_static_files_router():

Passing options to the router generated by create_static_files_router()#

from litestar import Litestar
from litestar.static_files import create_static_files_router

app = Litestar(
    route_handlers=[
        create_static_files_router(
            path="/",
            directories=["assets"],
            opt={"some": True},
            include_in_schema=False,
            tags=["static"],
        )
    ]
)

Using a custom router class#

The router class used can be customized with the router_class parameter:

Using a custom router class with create_static_files_router()#

from litestar import Litestar
from litestar.router import Router
from litestar.static_files import create_static_files_router


class MyRouter(Router):
    pass


app = Litestar(
    route_handlers=[
        create_static_files_router(
            path="/static",
            directories=["assets"],
            router_class=MyRouter,
        )
    ]
)

Retrieving paths to static files#

route_reverse() and url_for() can be used to retrieve the path under which a specific file will be available:

Retrieving paths to static files using route_reverse()#

from litestar import Litestar
from litestar.static_files import create_static_files_router

app = Litestar(
    route_handlers=[
        create_static_files_router(path="/static", directories=["assets"]),
    ]
)


print(app.route_reverse(name="static", file_path="/some_file.txt"))  # /static/some_file.txt

Tip

The name parameter has to match the name parameter passed to create_static_files_router(), which defaults to static.

(Remote) file systems#

To customize how Litestar interacts with the file system, a class implementing the FileSystemProtocol can be passed to file_system. An example of this are the file systems provided by fsspec, which includes support for FTP, SFTP, Hadoop, SMB, GitHub and many more, with support for popular cloud providers available via 3rd party implementations such as

S3 via S3FS
Google Cloud Storage via GCFS
Azure Blob Storage via adlfs

Using a custom file system with create_static_files_router()#

from fsspec.implementations.ftp import FTPFileSystem

from litestar import Litestar
from litestar.static_files import create_static_files_router

app = Litestar(
    route_handlers=[
        create_static_files_router(
            path="/static",
            directories=["assets"],
            file_system=FTPFileSystem(host="127.0.0.1"),
        ),
    ]
)

Upgrading from legacy StaticFilesConfig#

Deprecated since version v3.0: StaticFilesConfig is deprecated and will be removed in Litestar 3.0

Existing code can be upgraded to create_static_files_router() by replacing StaticFilesConfig instances with this function call and passing the result to route_handlers instead of static_files_config:

Using the deprecated StaticFilesConfig#

from litestar import Litestar
from litestar.static_files.config import StaticFilesConfig

app = Litestar(
    static_files_config=[
        StaticFilesConfig(directories=["assets"], path="/static"),
    ],
)

Upgrading from StaticFilesConfig to create_static_files_router()#

from litestar import Litestar
from litestar.static_files import create_static_files_router

app = Litestar(
    route_handlers=[
        create_static_files_router(directories=["assets"], path="/static"),
    ],
)