starlette-csrf

What it is and what it does

Starlette CSRF is a middleware package that guards Starlette and FastAPI applications against cross-site request forgery attacks. It implements the Double Submit Cookie pattern: on safe HTTP methods (GET, HEAD, OPTIONS, TRACE by default), it sets a cookie containing a secret token; on unsafe methods (POST, PUT, DELETE, PATCH), it requires the same token to be sent in a request header, comparing the two to verify the request originated from your application.

The middleware is configurable for different authentication schemes, URL patterns, and cookie settings. You can exempt specific URLs from CSRF checks, enforce checks on particular URLs regardless of method, or restrict CSRF validation to requests that carry certain cookies. It depends only on itsdangerous (for token signing) and starlette itself, making it lightweight to integrate into existing Starlette or FastAPI applications.

Use it for:

• Protect form submissions and API endpoints in browser-based Starlette applications from CSRF attacks.
• Customize CSRF error responses (e.g., return JSON instead of plain text) by subclassing the middleware.
• Exempt specific API routes that don't require CSRF protection while enforcing it elsewhere.
• Configure different cookie domains to allow frontend and API subdomains to share CSRF tokens.
• Restrict CSRF checks to requests carrying session cookies while allowing stateless API calls.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Starlette middleware that protects web applications from CSRF attacks using the Double Submit Cookie technique, validating that unsafe requests include a matching token in both a cookie and a request header.

Yes, if you are building a Starlette or FastAPI application with cookie-based authentication and need CSRF protection. The package is stable, has no known vulnerabilities, and integrates cleanly with minimal dependencies. However, note that maintenance is aging (last release June 2023); verify compatibility with your current Starlette version and monitor the repository for any future security updates.

Install

starlette-csrf on PyPI

pip install starlette-csrf

uv add starlette-csrf

poetry add starlette-csrf

Installing starlette-csrf

Before you install

Low friction installation with only two runtime dependencies (itsdangerous and starlette). Maintenance status is aging—last release was 2023-06-27 and no commits since 2025-03-15—but the package is marked Production/Stable and has seen no security vulnerabilities.

License in practice

MIT license (permissive) means you can use, modify, and distribute this package freely in both open-source and commercial projects with minimal restrictions.

Quickstart

pip install starlette-csrf

from starlette.applications import Starlette
from starlette.middleware import Middleware
from starlette_csrf import CSRFMiddleware

middleware = [Middleware(CSRFMiddleware, secret="__CHANGE_ME__")]
app = Starlette(routes=routes, middleware=middleware)

Requires a strong secret passphrase to be set; using the default placeholder will not provide security.

Verify before relying

• Whether the aging maintenance status (last release June 2023) affects compatibility with current Starlette versions.
• Performance impact of CSRF token validation on high-traffic applications.
• Whether cookie_secure=False default is appropriate for production deployments.

Package facts

Evidence: starlette_csrf-3.0.0-py3-none-any.whl

Tags

More Session packages