Skip to main content
Firestore Pydantic ODM gives Python developers a clean, type-safe layer over Google Cloud Firestore. Define your data models as Pydantic classes, then use async CRUD methods, rich query filters, projections, subcollections, and atomic batch writes—all with zero boilerplate.

Quickstart

Connect to Firestore and run your first async query in under five minutes.

Installation

Install via pip and set up credentials for production or the local emulator.

Core Concepts

Learn how models, the database client, and subcollections fit together.

API Reference

Full reference for every class, method, enum, and field descriptor.

​
Why Firestore Pydantic ODM?

Firestore’s native Python SDK is powerful but low-level: you work directly with dictionaries, manage document references by hand, and write your own serialization logic. Firestore Pydantic ODM sits on top of that SDK and gives you:
  • Pydantic validation — every document is validated on read and write.
  • Async-first — all I/O uses async/await with google-cloud-firestore’s AsyncClient.
  • Pythonic filters — write User.age >= 18 instead of string-based where clauses.
  • Projections — define a lightweight Pydantic model to fetch only the fields you need.
  • Subcollections — declare parent–child relationships directly in the model Settings.
  • Pydantic v1 & v2 — works transparently with either major version.

​
Get started in three steps

1

Install the package

pip install firestore-pydantic-odm
2

Define a model and initialise the database

from firestore_pydantic_odm import BaseFirestoreModel, FirestoreDB, init_firestore_odm

class User(BaseFirestoreModel):
    class Settings:
        name = "users"   # Firestore collection name

    name: str
    email: str

db = FirestoreDB(project_id="my-gcp-project")
init_firestore_odm(db, [User])
3

Run async CRUD

import asyncio

async def main():
    user = User(name="Alice", email="[email protected]")
    await user.save()

    async for u in User.find(filters=[User.name == "Alice"]):
        print(u.email)

asyncio.run(main())
Use the Firestore emulator for local development and CI. Pass emulator_host="localhost:8080" to FirestoreDB to route all traffic locally.