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.

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=True flag will send them with a Content-Disposition: attachment instead:

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=True. This will:

• Serve and /index.html when the path / is requested

• Attempt to serve /404.html when a requested file is not found

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():

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:

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:

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

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

Important

Info 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:

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

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

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"),
    ],
)