beanie

What it is and what it does

Beanie is an asynchronous ODM (object-document mapper) that sits on top of PyMongo and Pydantic, letting you define MongoDB collections as Python classes with type hints and validation. Instead of writing raw MongoDB queries, you work with Document subclasses that map to collections, and Beanie handles the serialization, validation, and async I/O for you.

It's designed to reduce boilerplate when building async Python applications that use MongoDB—particularly useful in FastAPI projects or other async frameworks. You define a Document class with Pydantic fields, initialize Beanie with your MongoDB client, and then use methods like insert(), find_one(), and set() on your document instances. The package handles data migrations and index definitions declaratively.

Use it for:

• Building FastAPI REST APIs backed by MongoDB with async request handlers and Pydantic validation.
• Defining MongoDB schemas as Python classes to enforce type safety and validation across your application.
• Querying MongoDB collections using Python syntax (e.g., Product.price < 10) instead of raw MongoDB query dictionaries.
• Managing document relationships and nested Pydantic models within MongoDB documents.
• Handling database migrations and index creation declaratively as part of your Document class definitions.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Beanie is an asynchronous Python object-document mapper for MongoDB that lets you define data models using Pydantic and interact with MongoDB collections through a Document-based API.

Yes. Beanie is actively maintained, has no known vulnerabilities, low install friction, and a permissive license. It's a solid choice if you're building async Python applications with MongoDB and want type-safe, Pydantic-based data models. The main constraint is that you must be using async/await and have MongoDB available; if you need synchronous access, the project maintains a separate package called Bunnet.

Install

beanie on PyPI

pip install beanie

uv add beanie

poetry add beanie

Installing beanie

Before you install

Low friction installation with a pure-Python wheel. Actively maintained as of 2026-08-10 with recent release history. Depends on pydantic, pymongo, click, lazy-model, and typing-extensions—all stable, widely-used packages.

License in practice

Licensed under Apache Software License (permissive), so you can use it freely in commercial and open-source projects without copyleft obligations.

Quickstart

pip install beanie

import asyncio
from pymongo import AsyncMongoClient
from beanie import Document, init_beanie

class Product(Document):
    name: str
    price: float

async def main():
    client = AsyncMongoClient("mongodb://localhost:27017")
    await init_beanie(database=client.db_name, document_models=[Product])
    product = await Product.find_one(Product.price < 10)

asyncio.run(main())

Requires MongoDB server running and accessible; async/await syntax requires Python 3.10 or later.

Verify before relying

• Whether schema migrations are automatic or require manual setup steps.
• Performance characteristics compared to raw pymongo for large datasets.
• Whether the Indexed() syntax supports all MongoDB index types.

Package facts

Evidence: beanie-2.2.0-py3-none-any.whl

Keywords: mongodb, odm, orm, pydantic, mongo, async, python

Tags

More Python Modules packages