---
id: pydantic-mongo
version: "3.1.0"
license: MIT
license_treatment: permissive
maintenance: aging
---

# pydantic-mongo — Document object mapper for pydantic and pymongo

License: permissive · Maintenance: aging · Downloads: 182.3K/mo

## What it is and what it does

Pydantic Mongo is a thin wrapper around pymongo that applies the Repository pattern, letting you define MongoDB collections as Pydantic models and interact with them through a type-safe, validated interface. It handles the boilerplate of connecting Pydantic's validation and serialization to MongoDB's document model, so you define your schema once as a Pydantic class and then use repository methods (save, find_one_by_id, find_by, delete, etc.) to perform CRUD operations without writing raw MongoDB queries.

The package supports both synchronous (via AbstractRepository) and asynchronous (via AsyncAbstractRepository) workflows, making it suitable for blocking and non-blocking applications. It depends on pymongo for the driver layer and pydantic for validation, so you inherit both their capabilities and constraints—notably, you still need a MongoDB server running, and your models must be valid Pydantic classes.

Use it for:

- Building a REST API where each endpoint maps to a Pydantic model stored in MongoDB, with automatic validation on save.
- Writing async FastAPI handlers that query MongoDB without writing raw pymongo code or managing connection pooling manually.
- Migrating from a different ORM to MongoDB while keeping your existing Pydantic schemas and validation logic.
- Implementing cursor-based pagination for large result sets in a web application.
- Defining type-safe repository classes for unit testing with mock repositories that share the same interface.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

Provides a Repository pattern for MongoDB with Pydantic model integration, supporting both synchronous and asynchronous CRUD operations with built-in validation and serialization.

Yes, if you are already using Pydantic and MongoDB together. The package reduces boilerplate and provides a clean, type-safe interface for common CRUD patterns. Maintenance is aging but active, with no security issues. Install friction is low. The main trade-off is that you are adding a thin abstraction layer—if you need fine-grained control over MongoDB queries or aggregation pipelines, you may find the repository pattern limiting and prefer working directly with pymongo.

## Install

pip install pydantic-mongo
uv add pydantic-mongo
poetry add pydantic-mongo

## Installing pydantic-mongo

Before you install: Low install friction with a pure Python wheel. Maintenance is aging—last commit was 2025-10-13, but the project remains active and supports current Python versions (3.9, 3.10, 3.11). No known vulnerabilities.

License in practice: MIT license is permissive; you can use, modify, and distribute this package freely in commercial and private projects with minimal restrictions.

Quickstart:

pip install pydantic-mongo

from pydantic import BaseModel
from pydantic_mongo import AbstractRepository
from pymongo import MongoClient

class MyModel(BaseModel):
    name: str

class MyRepository(AbstractRepository[MyModel]):
    class Meta:
        collection_name = 'items'

client = MongoClient('mongodb://localhost:27017')
db = client['mydb']
repo = MyRepository(db)

item = MyModel(name='test')
repo.save(item)

Requires a running MongoDB instance accessible at the connection string you provide.

Verify before relying:

- Whether cursor-based pagination handles large result sets efficiently in practice.
- Performance characteristics when working with deeply nested Pydantic models.
- Compatibility guarantees with future versions of pymongo and pydantic.

## Package facts

- License: MIT (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: aging
- Downloads: 182.3K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

mongodb repository pattern, pydantic mongo orm, async mongodb operations, document mapper pydantic, mongodb crud helper, type-safe mongodb queries, mongo repository abstraction, mongodb-orm, pydantic-integration, async-support

[View on SkillFed](https://skillfed.io/packages/pydantic-mongo) · [View on PyPI](https://pypi.org/project/pydantic-mongo/)