---
id: beanie
version: "2.2.0"
license: unclear
license_treatment: permissive
maintenance: active
---

# beanie — Asynchronous Python ODM for MongoDB

License: permissive · Maintenance: active · Downloads: 1.7M/mo

## 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 above — 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

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

- License: not declared (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 1.7M/month (top 5,000 on PyPI)
- Known vulnerabilities: none known

## Tags

mongodb async odm python, pydantic mongodb mapper, async document database orm, mongodb object mapper, beanie odm, pymongo async wrapper, mongodb schema validation, mongodb, async-orm, pydantic-integration

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