Starlette

Warnings

• breaking on_startup= and on_shutdown= parameters removed in 1.0. add_event_handler() also removed. All three were the primary patterns in older tutorials and LLM-generated code.
  Fix: Use lifespan context manager: @asynccontextmanager async def lifespan(app): yield — pass as app = Starlette(lifespan=lifespan).
• breaking @app.route() and @app.websocket_route() decorators removed in 1.0. Were deprecated since 0.23.0 but widely used in tutorials for years.
  Fix: Use declarative routing: Starlette(routes=[Route('/', handler), WebSocketRoute('/ws', ws_handler)]).
• breaking Jinja2Templates now raises ImportError at import time if jinja2 is not installed. Previously only raised when instantiating the class.
  Fix: pip install jinja2 or pip install 'starlette[full]'
• breaking Jinja2Templates now enables autoescape by default. Templates that relied on unescaped output (e.g. rendering HTML strings) will now escape them.
  Fix: Mark trusted HTML strings with Markup() from markupsafe, or pass autoescape=False to Jinja2Templates() to restore old behavior.
• breaking TestClient now uses httpx instead of requests (changed in 0.20.0). Test suites using requests-specific APIs on TestClient responses will break.
  Fix: pip install httpx. Use httpx response API — most methods are compatible. Use the bump-testclient migration tool for larger test suites.
• breaking Python 3.8 and 3.9 support dropped. Starlette 1.0 requires Python >=3.10.
  Fix: Upgrade Python to 3.10+. Pin starlette<1.0 to remain on Python 3.8/3.9.
• gotcha Starlette is typically a transitive dependency via FastAPI — do not pin starlette version directly. FastAPI manages its own compatible Starlette range. Pinning starlette independently can cause conflicts.
  Fix: Let FastAPI manage the starlette version. Only pin starlette directly if using it standalone without FastAPI.

Install

• pip install starlette Core
• pip install "starlette[full]" With all optional extras (jinja2, python-multipart, httpx, itsdangerous, pyyaml)

Imports

• lifespan

  from contextlib import asynccontextmanager
  from starlette.applications import Starlette
  
  @asynccontextmanager
  async def lifespan(app):
      # startup
      yield
      # shutdown
  
  app = Starlette(lifespan=lifespan)

  on_startup and on_shutdown parameters removed in 1.0. The lifespan context manager is the only supported pattern.
• Route (declarative)

  from starlette.applications import Starlette
  from starlette.routing import Route
  
  async def homepage(request):
      ...
  
  app = Starlette(routes=[Route('/', homepage)])

  @app.route() and @app.websocket_route() decorators removed in 1.0. Use declarative Route() objects in the routes list.

Quickstart

Minimal Starlette 1.0 app with lifespan and declarative routing.

from contextlib import asynccontextmanager
from starlette.applications import Starlette
from starlette.requests import Request
from starlette.responses import JSONResponse
from starlette.routing import Route

@asynccontextmanager
async def lifespan(app):
    # startup logic
    yield
    # shutdown logic

async def homepage(request: Request):
    return JSONResponse({'hello': 'world'})

app = Starlette(
    routes=[Route('/', homepage)],
    lifespan=lifespan,
)

# Run: uvicorn main:app