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 BaseFileSystem or any fsspec file system can be passed to file_system, providing integrations 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"),
        ),
    ]
)