Install & Compatibility
Where this runs
tested against v2.24.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 1.306s · 88.1MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 7.5s · import 1.236s · 93MB
91MB installed
● package 91MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Litestar
✓ from litestar import Litestar
get
✓ from litestar import get
post
✓ from litestar import post
Controller
✓ from litestar import Controller
ASGIMiddleware
✓ from litestar.middleware import ASGIMiddleware
✗ from litestar.middleware.base import AbstractMiddleware
The `AbstractMiddleware` class was deprecated in Litestar v2.15, favoring `ASGIMiddleware` for creating custom middleware.
AsyncTestClient
✓ from litestar.testing import AsyncTestClient
✗ from litestar.testing import TestClient
`TestClient` can cause event loop issues with async fixtures; `AsyncTestClient` is recommended for async testing.
ASGIConnection
✓ from litestar.connection import ASGIConnection
✗ from starlite.ASGIConnection
Following the rebranding from Starlite to Litestar in v2.0, all top-level imports and sub-package paths changed.
This minimal example demonstrates how to create a Litestar application with a single GET endpoint. It uses an environment variable for a customizable greeting. The 'litestar run' command requires 'uvicorn', which is included with the 'standard' extra.
from litestar import Litestar, get
import os
@get("/")
async def hello_world() -> str:
return f"Hello, {os.environ.get('NAME', 'World')}!"
app = Litestar(route_handlers=[hello_world])
# To run this application:
# 1. Save it as app.py
# 2. Run in terminal: litestar run --reload
# 3. Access at http://127.0.0.1:8000/
litestar --version
Debug
Known issues
breakingProject Rebranding (Starlite to Litestar): With the release of v2.0, the framework was renamed from 'Starlite' to 'Litestar'. All import paths must be updated accordingly (e.g., `from starlite import ...` becomes `from litestar import ...`).fixUpdate all `starlite` imports to `litestar`. Review the official v2 migration guide for a complete list of changes.
affects: 2.0.0 and later
breakingPydantic Integration Changes: Pydantic was removed from Litestar's core in v2.0, making it an optional dependency. While Pydantic models are still fully supported via a plugin, the framework's internal data handling switched to `msgspec` for performance. If you were implicitly relying on Pydantic for non-Pydantic types, behavior might differ.fixExplicitly install `pydantic` if you need to use Pydantic models. For non-Pydantic types (dataclasses, attrs, msgspec structs), ensure they are correctly typed; Litestar will handle them directly, potentially improving performance.
affects: 2.0.0 and later
breakingMiddleware API Evolution: The `MiddlewareProtocol` and `AbstractMiddleware` classes were deprecated around v2.15 in favor of the `ASGIMiddleware` abstract base class. This change simplifies middleware configuration and dispatching.fixMigrate custom middleware implementations to extend `litestar.middleware.ASGIMiddleware` instead of `AbstractMiddleware`.
affects: 2.15.0 and later
gotchaStrict Type Hinting Enforcement: Litestar rigorously uses and enforces Python type hints for data validation, parsing, serialization, and OpenAPI schema generation. Failing to provide accurate type hints (e.g., return types for route handlers) can lead to runtime exceptions.fixAlways use precise type hints for function arguments and return values in route handlers, dependencies, and DTOs. Ensure Pydantic models, dataclasses, or other data structures are correctly defined.
affects: All v2.x versions
gotchaEvent Loop Management in Async Tests: When using `httpx.AsyncClient` or the synchronous `TestClient` with async testing frameworks like `pytest-asyncio`, running the Litestar application in a different event loop than the test/fixture can lead to `RuntimeError: Event loop is closed`. This is a common pitfall in async Python testing.fixPrefer `litestar.testing.AsyncTestClient` for asynchronous tests, as it's designed to manage event loops correctly within the test context. Ensure your test setup respects the asynchronous nature of the client and application.
affects: All v2.x versions
gotchaException Handler Scope for 404/405 Errors: `NotFoundException` (404) and `MethodNotAllowedException` (405) are raised by Litestar's ASGI Router before the middleware stack is fully invoked. Consequently, these exceptions can only be handled by exception handlers registered directly on the `Litestar` application instance, not by handlers defined on specific controllers or route handlers.fixIf you need to customize responses for 404 or 405 errors, ensure their exception handlers are passed directly to the `Litestar` constructor when initializing your application.
affects: All v2.x versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'litestar'
The `litestar` package or one of its required dependencies (like `annotated-types` or `sniffio`) is not installed in the active Python environment, or the virtual environment is not activated.
fixEnsure you have activated your virtual environment and installed Litestar with its standard dependencies: `pip install 'litestar[standard]'` or explicitly install missing dependencies, e.g., `pip install annotated-types sniffio`.
AttributeError: 'coroutine' object has no attribute 'to_asgi_response'
This error typically occurs when an asynchronous route handler function is called or treated as a synchronous function, or when an `async def` function is returned directly without awaiting it in a context that expects a synchronous return or an ASGI response object.
fixEnsure that asynchronous handler functions are properly awaited or handled within an `async` context. If you are returning a value from an `async` handler, Litestar handles its serialization, but direct manual manipulation of ASGI responses should be done carefully to ensure correct async execution.
litestar.exceptions.MissingDependencyException
This exception is raised when your Litestar application attempts to use a feature that relies on an optional dependency (e.g., a database plugin, templating engine) that has not been installed in your Python environment.
fixInstall the missing dependency. For example, if using the SQLAlchemy plugin, run `pip install 'litestar[sqlalchemy]'` or `pip install sqlalchemy`.
litestar.exceptions.ValidationException
This error indicates that incoming request data (e.g., JSON payload, form data, query parameters) failed validation against the expected types or DTOs defined in your Litestar route handler, often due to Pydantic validation failures.
fixReview the data being sent in the request to ensure it conforms to the expected schema (types, required fields, formats) defined by your route handler's type hints or DTOs. The exception's `extra` field often contains detailed validation errors.
RuntimeError: A route with the given name could not be found
This error occurs when attempting to reverse-lookup a URL (using `app.route_reverse()` or `request.app.url_for()`) for a route handler that either does not exist, or has not been assigned a `name` parameter in its decorator (e.g., `@get(path='/my-path', name='my_handler_name')`), or the provided name is incorrect.
fixEnsure that the route handler you are trying to reference has an explicit `name` argument in its decorator, and that the name used in `route_reverse()` or `url_for()` exactly matches it.
Upgrade
Version history
2.24.0latest on PyPI · released Jun 11, 2026
Audit
Dependencies
uvicornoptionalRecommended ASGI web server, included with 'litestar[standard]' extra.
pydanticoptionalOptional data validation and settings management. While Litestar's core uses msgspec, Pydantic is fully supported via a plugin for model definition and validation.
sqlalchemyoptionalFor database integration, especially when using the SQLAlchemyPlugin (requires SQLAlchemy 2.x).
aiosqliteoptionalAsynchronous driver for SQLite, often used with SQLAlchemy for async database operations.
greenletoptionalRequired for SQLAlchemy's async support with some database drivers.