Litestar is a powerful, flexible, highly performant, and opinionated ASGI framework.
The Litestar framework supports :doc:`/usage/plugins/index`, ships with :doc:`dependency injection </usage/dependency-injection>`, :doc:`security primitives </usage/security/index>`, :doc:`OpenAPI schema generation </usage/openapi/index>`, MessagePack, :doc:`middlewares </usage/middleware/index>`, a great :doc:`CLI </usage/cli>` experience, and much more.
pip install litestarTip
litestar[standard] includes commonly used extras like uvicorn and jinja2 (for templating).
.. dropdown:: Extras
:icon: star
`Pydantic <https://docs.pydantic.dev/latest/>`_
:code:`pip install litestar[pydantic]`
`Attrs <https://www.attrs.org>`_
:code:`pip install litestar[attrs]`
:ref:`Brotli Compression Middleware <usage/middleware/builtin-middleware:brotli>`:
:code:`pip install litestar[brotli]`
:ref:`Cookie Based Sessions <usage/middleware/builtin-middleware:client-side sessions>`
:code:`pip install litestar[cryptography]`
:doc:`JWT </usage/security/jwt>`
:code:`pip install litestar[jwt]`
:doc:`RedisStore </usage/stores>`
:code:`pip install litestar[redis]`
:ref:`Picologging <usage/logging:using picologging>`
:code:`pip install litestar[picologging]`
:ref:`StructLog <usage/logging:using structlog>`
:code:`pip install litestar[structlog]`
:doc:`Prometheus Instrumentation </usage/metrics/prometheus>`
:code:`pip install litestar[prometheus]`
:doc:`Open Telemetry Instrumentation </usage/metrics/open-telemetry>`
:code:`pip install litestar[opentelemetry]`
:doc:`SQLAlchemy </usage/databases/sqlalchemy/index>`
:code:`pip install litestar[sqlalchemy]`
:doc:`CLI </usage/cli>`
.. deprecated:: 2.1.1
The ``litestar`` base installation now includes the CLI dependencies and this group is no longer required
to use the CLI.
If you need the optional CLI dependencies, install the ``standard`` group instead.
**Will be removed in 3.0**
:code:`pip install litestar[cli]`
:doc:`Jinja Templating </usage/templating>`
:code:`pip install litestar[jinja]`
:doc:`Mako Templating </usage/templating>`
:code:`pip install litestar[mako]`
Standard Installation (includes Uvicorn and Jinja2 templating):
:code:`pip install litestar[standard]`
All Extras:
:code:`pip install litestar[full]`
.. note:: The full extras is not recommended because it will add a lot of unnecessary extras.
At a minimum, make sure you have installed litestar[standard], which includes uvicorn.
First, create a file named app.py with the following contents:
from litestar import Litestar, get
@get("/")
async def index() -> str:
return "Hello, world!"
@get("/books/{book_id:int}")
async def get_book(book_id: int) -> dict[str, int]:
return {"book_id": book_id}
app = Litestar([index, get_book])Then, run the following command:
litestar run
# Or you can run Uvicorn directly:
uvicorn app:app --reloadYou can now visit http://localhost:8000/ and http://localhost:8000/books/1 in your browser and
you should see the responses of your two endpoints:
"Hello, world!"
and
{"book_id": 1}Tip
You can also check out the automatically generated OpenAPI-based documentation at:
http://localhost:8000/schema(for ReDoc),http://localhost:8000/schema/swagger(for Swagger UI),http://localhost:8000/schema/elements(for Stoplight Elements)http://localhost:8000/schema/rapidoc(for RapiDoc)
You can check out a more in-depth tutorial in the :doc:`/tutorials/todo-app/index` section!
Litestar is a community-driven open-source initiative that thrives on the generous contributions of our sponsors, enabling us to pursue innovative developments.
A huge thank you to our current sponsors:
Scalar.com
Telemetry Sports
Stok
We invite organizations and individuals to join our sponsorship program. By becoming a sponsor on Polar (preferred), or other platforms like GitHub and Open Collective, you can play a pivotal role in our project's growth.
Also, exclusively with Polar, you can engage in pledge-based sponsorships.
Define your data model using pydantic or any library based on it (for example ormar, beanie, SQLModel):
from pydantic import BaseModel, UUID4
class User(BaseModel):
first_name: str
last_name: str
id: UUID4You can also use dataclasses (standard library and Pydantic), :class:`typing.TypedDict`, or :class:`msgspec.Struct`.
from uuid import UUID
from dataclasses import dataclass
from litestar.dto import DTOConfig, DataclassDTO
@dataclass
class User:
first_name: str
last_name: str
id: UUID
class PartialUserDTO(DataclassDTO[User]):
config = DTOConfig(exclude={"id"}, partial=True)Define a Controller for your data model:
from typing import List
from litestar import Controller, get, post, put, patch, delete
from litestar.dto import DTOData
from pydantic import UUID4
from my_app.models import User, PartialUserDTO
class UserController(Controller):
path = "/users"
@post()
async def create_user(self, data: User) -> User: ...
@get()
async def list_users(self) -> List[User]: ...
@patch(path="/{user_id:uuid}", dto=PartialUserDTO)
async def partial_update_user(
self, user_id: UUID4, data: DTOData[User]
) -> User: ...
@put(path="/{user_id:uuid}")
async def update_user(self, user_id: UUID4, data: User) -> User: ...
@get(path="/{user_id:uuid}")
async def get_user(self, user_id: UUID4) -> User: ...
@delete(path="/{user_id:uuid}")
async def delete_user(self, user_id: UUID4) -> None: ...When instantiating your app, import your controller into your application's entry-point and pass it to Litestar:
from litestar import Litestar
from my_app.controllers.user import UserController
app = Litestar(route_handlers=[UserController])To run your application, use an ASGI server such as uvicorn :
uvicorn my_app.main:app --reload- Litestar is a community-driven project. This means not a single author, but rather a core team of maintainers is leading the project, supported by a community of contributors. Litestar currently has 5 maintainers and is being very actively developed.
- Litestar draws inspiration from NestJS - a contemporary TypeScript framework - which places opinions and patterns at its core.
- While still allowing for function-based endpoints, Litestar seeks to build on Python's powerful and versatile OOP, by placing class-based controllers at its core.
- Litestar is not a microframework. Unlike frameworks such as FastAPI, Starlette, or Flask, Litestar includes a lot of functionalities out of the box needed for a typical modern web application, such as ORM integration, client- and server-side sessions, caching, OpenTelemetry integration, and many more. It's not aiming to be "the next Django" (for example, it will never feature its own ORM), but its scope is not micro either.
- litestar-fullstack : A fully-capable, production-ready fullstack
Litestar web application configured with best practices. It includes SQLAlchemy 2.0, VueJS, Vite,
SAQ job queue,
Jinjatemplates and more. Read more. Like all Litestar projects, this application is open to contributions, big and small. - litestar-fullstack-inertia : Similar to Litestar Fullstack but uses Inertia.js.
- litestar-hello-world: A bare-minimum application setup. Great for testing and POC work.
.. toctree::
:titlesonly:
:caption: Documentation
:hidden:
usage/index
reference/index
benchmarks
.. toctree::
:titlesonly:
:caption: Guides
:hidden:
migration/index
topics/index
tutorials/index
.. toctree::
:titlesonly:
:caption: Contributing
:hidden:
contribution-guide
Available Issues <https://github.com/search?q=user%3Alitestar-org+state%3Aopen+label%3A%22good+first+issue%22+++no%3Aassignee+&type=issues>
Code of Conduct <https://github.com/litestar-org/.github?tab=coc-ov-file#readme>