Async MongoDB ODM for Python

Model clearly.
Query without surprises.

Mongoz brings typed documents, immutable query building, deliberate index management, and native PyMongo Async boundaries into one focused data layer.

Build your first document Upgrade from older Mongoz

pip install mongoz

from mongoz import Document, Registry, String

registry = Registry("mongodb://localhost:27017")

class User(Document):
    name: str = String(min_length=1, max_length=80)
    email: str = String(unique=True)

    class Meta:
        registry = registry
        database = "app"

async with registry:
    user = await User.objects.create(
        name="Ada",
        email="ada@example.com",
    )
    active = await User.objects.filter(name__startswith="A")

Python 3.10–3.14 PyMongo Async Pydantic 2 Typed package

Documents with boundaries¶

Pydantic-backed documents validate modeled fields and serialize deliberately to BSON. Embedded documents, references, inheritance, and native-driver escape hatches stay explicit.

Understand documents →

Queries you can compose¶

Managers and QuerySets use clone-on-write state, so deriving a filter, sort, projection, limit, or session-bound query does not mutate the query you started from.

Explore querying →

Index changes you can inspect¶

Plan index reconciliation before execution. Mongoz retains unmanaged indexes unless deletion is explicitly authorized and treats conflicting names as a decision, not a guess.

Plan indexes →

Native where it matters¶

Sessions, transactions, timeouts, concerns, monitoring, and deployment topology remain PyMongo and MongoDB contracts. Mongoz exposes the driver objects instead of hiding them.

Run in production →

A realistic first flow¶

Mongoz does no database or index I/O when a document class is imported. Create one Registry for the application lifecycle, use document managers for modeled operations, and close the Registry on shutdown. For bounded scripts, the async context manager owns cleanup.

from mongoz import Document, Integer, Registry, String

registry = Registry("mongodb://localhost:27017")

class Book(Document):
    title: str = String(min_length=1)
    year: int = Integer(minimum=1450)

    class Meta:
        registry = registry
        database = "library"

async def main() -> None:
    async with registry:
        book = await Book.objects.create(title="The Left Hand of Darkness", year=1969)
        found = await Book.objects.get(id=book.id)
        await found.update(year=1969)
        await found.delete()

Choose the next path

New users should continue with Installation and the Quickstart. Existing applications should read the modernization migration guide before changing dependencies or lifecycle code.

Model clearly.Query without surprises.