Install & Compatibility
Where this runs
tested against v15.0.5 · 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.915 runs
installs and imports cleanly · install 0.0s · import 2.266s · 78.9MB
glibcpy 3.10–3.915 runs
installs and imports cleanly · install 6.1s · import 2.120s · 76MB
78MB installed
● package 78MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
FastAPIUsers
✓ from fastapi_users import FastAPIUsers
SQLAlchemyUserDatabase
✓ from fastapi_users_db_sqlalchemy import SQLAlchemyUserDatabase
BearerBackend
✓ from fastapi_users.authentication import BearerBackend
CookieBackend
✓ from fastapi_users.authentication import CookieBackend
AuthenticationBackend
✓ from fastapi_users.authentication import AuthenticationBackend
UUIDIDStrategy
✓ from fastapi_users.authentication import JWTStrategy, Strategy, UUIDIDStrategy
This quickstart sets up a basic FastAPI application with user registration, login (using JWT stored in a cookie), and user management endpoints. It uses an in-memory SQLite database with SQLAlchemy for simplicity. Remember to replace the `SECRET` with a strong, environment-variable-managed secret in production.
import uuid
from typing import AsyncGenerator
from fastapi import Depends, FastAPI
from fastapi_users import FastAPIUsers, schemas
from fastapi_users.authentication import JWTStrategy, AuthenticationBackend, CookieBackend
from fastapi_users_db_sqlalchemy import SQLAlchemyUserDatabase, UUID_ID, SQLAlchemyBaseUserTableUUID
from sqlalchemy.ext.asyncio import AsyncSession, create_async_engine
from sqlalchemy.orm import sessionmaker, DeclarativeBase
DATABASE_URL = "sqlite+aiosqlite:///./test.db"
SECRET = "" # For JWT and Cookie backend, replace with os.environ.get('SECRET', '')
class Base(DeclarativeBase):
pass
class User(SQLAlchemyBaseUserTableUUID, Base):
pass
async def get_async_session() -> AsyncGenerator[AsyncSession, None]:
async_engine = create_async_engine(DATABASE_URL)
async_session_maker = sessionmaker(async_engine, class_=AsyncSession, expire_on_commit=False)
async with async_session_maker() as session:
yield session
async def create_db_and_tables():
async_engine = create_async_engine(DATABASE_URL)
async with async_engine.begin() as conn:
await conn.run_sync(Base.metadata.create_all)
async def get_user_db(session: AsyncSession = Depends(get_async_session)):
yield SQLAlchemyUserDatabase(session, User)
def get_jwt_strategy() -> JWTStrategy[User, UUID_ID]:
return JWTStrategy(secret=SECRET, lifetime_seconds=3600)
auth_backend = AuthenticationBackend(
name="jwt",
transport=CookieBackend(name="b", lifetime_seconds=3600, secret=SECRET),
get_strategy=get_jwt_strategy,
)
fastapi_users = FastAPIUsers[User, UUID_ID](
get_user_db,
[auth_backend],
)
app = FastAPI()
@app.on_event("startup")
async def on_startup():
await create_db_and_tables()
app.include_router(
fastapi_users.get_auth_router(auth_backend),
prefix="/auth/jwt",
tags=["auth"],
)
app.include_router(
fastapi_users.get_register_router(),
prefix="/auth",
tags=["auth"],
)
app.include_router(
fastapi_users.get_users_router(),
prefix="/users",
tags=["users"],
)
Errors
Common errors & fixes
ImportError: cannot import name 'SQLAlchemyBaseUserTableUUID' from 'fastapi_users.db'
This error occurs when the optional SQLAlchemy dependency is not installed.
fixInstall the package with SQLAlchemy support using: pip install 'fastapi-users[sqlalchemy]'
ModuleNotFoundError: No module named 'pkg_resources'
This error occurs when using Python 3.12, as 'pkg_resources' is deprecated and removed.
fixDowngrade to Python 3.11 or wait for an update that supports Python 3.12.
ImportError: cannot import name 'models' from 'fastapi_users'
This error occurs when there's a circular import, often due to naming a script 'fastapi_users.py'.
fixRename your script to avoid conflicts with the 'fastapi_users' module.
ModuleNotFoundError: No module named 'fastapi_users'
This error typically occurs when the `fastapi-users` library, or one of its required database integration packages, has not been installed in your Python environment or the virtual environment is not activated. It can also happen if specific database extras (like `[sqlalchemy]` or `[mongodb]`) were not included during installation.
fixEnsure you have installed `fastapi-users` with the necessary database integration. For SQLAlchemy, use: `pip install "fastapi-users[sqlalchemy]"`. For other databases, replace `sqlalchemy` with the appropriate extra, e.g., `[mongodb]` or `[tortoise-orm]`.
AttributeError: 'User' object has no attribute 'is_active'
This error means that your custom `User` model, which is used by `fastapi-users`, is missing the `is_active` attribute. The `BaseUser` (or `SQLAlchemyBaseUser`, etc.) classes provided by `fastapi-users` expect certain attributes like `is_active`, `is_superuser`, and `is_verified` to be present on your user model.
fixUpdate your custom `User` model to inherit from the correct base user class provided by `fastapi-users` (e.g., `fastapi_users.db.sqlalchemy.SQLAlchemyBaseUser`) and ensure it includes the `is_active`, `is_superuser`, and `is_verified` boolean fields, as well as `email` and `hashed_password`.
Upgrade
Version history
15.0.5latest on PyPI · released Mar 27, 2026
Audit
Dependencies
sqlalchemyoptionalRequired for SQLAlchemy-based user database backend.
mongodboptionalRequired for MongoDB-based user database backend.
tortoise-ormoptionalRequired for Tortoise ORM-based user database backend.
redisoptionalOptional, for advanced features like session storage or OTP via Redis.
pyjwt[crypto]requiredRequired for JWT token handling.
pwdlibrequiredPassword hashing library (replaces passlib as of v13).