Skip to main content
Firestore Pydantic ODM is distributed as a pure-Python package on PyPI and has no compiled extensions, making installation straightforward on any platform that runs Python 3.8 or later. This page covers the base install, the optional emulator extra, credential configuration for every environment, Pydantic version compatibility, and a quick verification snippet.

​
Install via pip

pip is the only supported package manager. Install the latest stable release with: 
pip install firestore-pydantic-odm

​
Optional extras

ExtraInstallsWhen to use
emulatorgoogle-cloud-firestore-emulatorLocal development and CI against the Firestore emulator
devblack, ruff, pytest, pytest-asyncio, httpxContributing to the library itself
Install with an extra by appending it in square brackets: 
# Emulator support only
pip install "firestore-pydantic-odm[emulator]"

# Emulator + dev tools (for contributors)
pip install "firestore-pydantic-odm[emulator,dev]"

​
Python Version Requirements

Firestore Pydantic ODM requires Python 3.8 or later. The test matrix covers Python 3.9 through 3.12 on every release. Python 3.8 is supported by the install configuration but not included in the CI matrix.
The library relies on async/await, typing.ClassVar, typing.Optional, and typing.AsyncGenerator—all of which are available from Python 3.8 onwards.

​
Dependencies

The following packages are installed automatically when you run pip install firestore-pydantic-odm:
PackageRequired versionPurpose
pydantic>=1.5, <3.0.0Model definition, validation, and serialization
google-cloud-firestore>=2.11.0Async Firestore client; FieldFilter requires ≥ 2.11.0
packaginglatestRuntime Pydantic version detection via packaging.version
google-cloud-firestore version 2.11.0 introduced the FieldFilter API. Installing an older version will cause an ImportError at query time. Always ensure your environment meets the minimum version.

​
Google Cloud Credentials

​
Production and staging

Firestore Pydantic ODM delegates all authentication to the Google Cloud client libraries, which follow the Application Default Credentials (ADC) resolution chain:
  1. GOOGLE_APPLICATION_CREDENTIALS environment variable — set this to the absolute path of a service-account JSON key file: 
    export GOOGLE_APPLICATION_CREDENTIALS="/path/to/service-account.json"
  2. gcloud user credentials — run gcloud auth application-default login on a developer machine to store user credentials that the library will pick up automatically.
  3. Attached service account — when running on Google Cloud infrastructure (Cloud Run, GKE, Cloud Functions, App Engine, Compute Engine), the metadata server provides credentials without any additional setup.
You can also pass an explicit credentials object directly to FirestoreDB: 
from google.oauth2 import service_account
from firestore_pydantic_odm import FirestoreDB

creds = service_account.Credentials.from_service_account_file(
    "/path/to/service-account.json"
)
db = FirestoreDB(project_id="my-gcp-project", credentials=creds)

​
Firestore emulator

For local development and CI, the Firestore emulator lets you run a full Firestore instance on your machine without a network connection or a real GCP project. Option 1 — environment variable (recommended for CI): 
export FIRESTORE_EMULATOR_HOST="localhost:8080"
When this variable is set, FirestoreDB automatically routes all traffic to the emulator. Option 2 — emulator_host= constructor argument: 
from firestore_pydantic_odm import FirestoreDB

db = FirestoreDB(project_id="my-gcp-project", emulator_host="localhost:8080")
Passing emulator_host= sets FIRESTORE_EMULATOR_HOST in the process environment automatically, so subsequent client creations in the same process also point to the emulator. Option 3 — use_emulator() at runtime: 
db = FirestoreDB(project_id="my-gcp-project")
db.use_emulator("localhost:8080")   # switches and recreates the async client
Call db.clear_emulator() to switch back to the production endpoint.
Install the emulator with pip install "firestore-pydantic-odm[emulator]" and start it with gcloud emulators firestore start --host-port=localhost:8080. The emulator requires the Google Cloud CLI to be installed.

​
Pydantic Version Compatibility

Both Pydantic v1 and Pydantic v2 are fully supported. The library ships an internal pydantic_compat module that inspects pydantic.VERSION at import time using packaging.version.Version and selects the correct shims automatically.
Pydantic versionSupportedNotes
v1 (>=1.5, <2.0)✅ YesConfig class, __fields__, .dict()
v2 (>=2.0, <3.0)✅ Yesmodel_config, model_fields, .model_dump()
No changes to your model definitions are required when switching between Pydantic versions. The compatibility layer handles:
  • model_dump vs .dict()
  • model_fields vs __fields__
  • ConfigDict vs inner Config class
  • PrivateAttr declaration differences
When running Pydantic v2, the library automatically sets model_config = ConfigDict(populate_by_name=True) on BaseFirestoreModel so that both field names and aliases are accepted on construction. The equivalent Config.allow_population_by_field_name = True is set for Pydantic v1.

​
Verify Your Installation

After installing, run the following snippet to confirm that the package imports correctly and that your credentials are configured: 
import asyncio
from firestore_pydantic_odm import (
    BaseFirestoreModel,
    FirestoreDB,
    init_firestore_odm,
)


class HealthCheck(BaseFirestoreModel):
    class Settings:
        name = "_health_check"

    status: str = "ok"


async def verify():
    # Replace with your project ID, or use the emulator
    db = FirestoreDB(project_id="my-gcp-project", emulator_host="localhost:8080")
    init_firestore_odm(db, [HealthCheck])

    doc = HealthCheck(status="ok")
    await doc.save()
    print(f"Saved document with id: {doc.id}")

    fetched = await HealthCheck.get(doc.id)
    print(f"Fetched status: {fetched.status}")

    await doc.delete()
    print("Document deleted — installation verified!")


asyncio.run(verify())
If the script prints the three confirmation lines without raising an exception, your installation and credentials are working correctly.
If you see google.auth.exceptions.DefaultCredentialsError, either set GOOGLE_APPLICATION_CREDENTIALS to a valid service-account file or start the emulator and set FIRESTORE_EMULATOR_HOST=localhost:8080 before running the script.