Install & Compatibility
Where this runs
tested against v1.9.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.920 runs
installs and imports cleanly · install 0.0s · import 0.000s · 57.5MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 6.7s · import 0.000s · 64MB
62MB installed
● package 62MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
JWTAuth
✓ from piccolo_api.auth.jwt import JWTAuth
✗ from piccolo_api.auth.jwt import JWTAuth
This quickstart demonstrates how to set up a basic Starlette application with JWT authentication using `piccolo-api`. It includes a public and a protected route, and shows how to configure `JWTAuth` middleware with a secret key and excluded paths. Remember to manage your secret keys securely, ideally via environment variables.
import os
from starlette.applications import Starlette
from starlette.responses import JSONResponse
from starlette.routing import Route
from piccolo_api import JWTAuth
# For demonstration, typically loaded from environment variables
SECRET_KEY = os.environ.get('JWT_SECRET_KEY', 'your_super_secret_key_here')
async def homepage(request):
return JSONResponse({'hello': 'world'})
async def protected_route(request):
return JSONResponse({'data': 'This is protected data!'})
routes = [
Route('/', homepage),
Route('/protected', protected_route)
]
middleware = [
JWTAuth(
secret_key=SECRET_KEY,
# Exclude paths that don't require authentication
excluded_paths=['/', '/docs'],
# Allow an endpoint to create a token for testing
# In a real app, this would be a login endpoint
get_token_response=lambda user_id: JSONResponse({'token': f'fake-jwt-token-for-{user_id}'})
)
]
app = Starlette(routes=routes, middleware=middleware)
# To run this:
# uvicorn your_module_name:app --port 8000 --reload
# Access with: http://127.0.0.1:8000/
# Try http://127.0.0.1:8000/protected with a valid JWT in Authorization header
# You can use the get_token_response for generating a dummy token in dev.
piccolo --version
Debug
Known issues
breakingPython 3.8 and 3.9 are no longer supported since `piccolo-api` version 1.6.0. The library now requires Python >= 3.10.fixUpgrade your Python environment to 3.10 or newer.
affects: >=1.6.0
breakingPydantic 2.8.0 introduced breaking changes that caused issues with `piccolo-api` versions prior to 1.4.1. If you use Pydantic 2.8.0 or newer with an older `piccolo-api`, you may encounter validation errors.fixUpgrade `piccolo-api` to version 1.4.1 or newer: `pip install --upgrade piccolo-api`.
affects: <1.4.1 when used with Pydantic >=2.8.0
gotchaMulti-Factor Authentication (MFA) features require additional optional dependencies (`cryptography` and `pynacl`). Using MFA without these installed will result in `ModuleNotFoundError`.fixInstall `piccolo-api` with the `mfa` extra: `pip install "piccolo-api[mfa]"`.
affects: All versions with MFA support (>=1.5.0)
gotchaWhen configuring Multi-Factor Authentication (MFA), it's highly recommended to provide sensitive encryption keys (e.g., `MFA_ENCRYPTION_KEY`) using environment variables for security reasons, rather than hardcoding them.fixLoad encryption keys from environment variables using `os.environ.get('MFA_ENCRYPTION_KEY')`. affects: All versions with MFA support (>=1.5.0)
Upgrade
Version history
1.9.0latest on PyPI · released Feb 11, 2026
Audit
Dependencies
piccolorequiredCore ORM integration
starletterequiredASGI framework dependency
uvicornrequiredASGI server for examples/development
pyjwtrequiredJSON Web Token handling
cryptographyoptionalRequired for Multi-Factor Authentication (MFA)
pynacloptionalRequired for Multi-Factor Authentication (MFA)