Asynchronous Python ODM for MongoDB
Project Links
Meta
Author: Roman Right
Requires Python: >=3.10,<3.14
Classifiers
License
- OSI Approved :: Apache Software License
Development Status
- 5 - Production/Stable
Intended Audience
- Developers
Operating System
- OS Independent
Topic
- Database
- Software Development :: Libraries :: Python Modules
Typing
- Typed
Programming Language
- Python
- Python :: 3
- Python :: 3 :: Only
- Python :: 3.10
- Python :: 3.11
- Python :: 3.12
- Python :: 3.13
Overview
Beanie - is an asynchronous Python object-document mapper (ODM) for MongoDB. Data models are based on Pydantic.
When using Beanie each database collection has a corresponding Document that
is used to interact with that collection. In addition to retrieving data,
Beanie allows you to add, update, or delete documents from the collection as
well.
Beanie saves you time by removing boilerplate code, and it helps you focus on the parts of your app that actually matter.
Data and schema migrations are supported by Beanie out of the box.
There is a synchronous version of Beanie ODM - Bunnet
Installation
PIP
pip install beanie
Poetry
poetry add beanie
For more installation options (eg: aws, gcp, srv ...) you can look in the getting started
Example
import asyncio
from typing import Optional
from pymongo import AsyncMongoClient
from pydantic import BaseModel
from beanie import Document, Indexed, init_beanie
class Category(BaseModel):
name: str
description: str
class Product(Document):
name: str # You can use normal types just like in pydantic
description: Optional[str] = None
price: Indexed(float) # You can also specify that a field should correspond to an index
category: Category # You can include pydantic models as well
# This is an asynchronous example, so we will access it from an async function
async def example():
# Beanie uses PyMongo async client under the hood
client = AsyncMongoClient("mongodb://user:pass@host:27017")
# Initialize beanie with the Product document class
await init_beanie(database=client.db_name, document_models=[Product])
chocolate = Category(name="Chocolate", description="A preparation of roasted and ground cacao seeds.")
# Beanie documents work just like pydantic models
tonybar = Product(name="Tony's", price=5.95, category=chocolate)
# And can be inserted into the database
await tonybar.insert()
# You can find documents with pythonic syntax
product = await Product.find_one(Product.price < 10)
# And update them
await product.set({Product.name:"Gold bar"})
if __name__ == "__main__":
asyncio.run(example())
Links
Documentation
- Doc - Tutorial, API documentation, and development guidelines.
Example Projects
- Activity Log & Notification Service - Real-time event ingestion with FastAPI, Beanie ODM, and DocumentDB (MongoDB-compatible), an async backend for high-volume activity events with aggregation statistics and WebSocket alerts by Khelan Modi
- fastapi-beanie-jwt - Sample FastAPI server with JWT auth and Beanie ODM by Michael duPont
- fastapi-cosmos-beanie - FastAPI + Beanie ODM + Azure Cosmos Demo Application by Anthony Shaw
- LCCN Predictor - Leetcode contest rating predictor (FastAPI + Beanie ODM + React) by L. Bao
- Shortify - URL shortener RESTful API (FastAPI + Beanie ODM + JWT & OAuth2) by Iliya Hosseini
Articles
- Announcing Beanie - MongoDB ODM
- Build a Cocktail API with Beanie and MongoDB
- MongoDB indexes with Beanie
- Beanie Projections. Reducing network and database load.
- Beanie 1.0 - Query Builder
- Beanie 1.8 - Relations, Cache, Actions and more!
Resources
2.2.0
Aug 07, 2026
2.1.0
Mar 26, 2026
2.0.1
Nov 20, 2025
2.0.0
Jul 20, 2025
1.30.0
Jun 10, 2025
1.29.0
Jan 06, 2025
1.28.0
Dec 08, 2024
1.27.0
Oct 07, 2024
1.26.0
May 01, 2024
1.25.0
Jan 25, 2024
1.24.0
Dec 24, 2023
1.23.6
Nov 13, 2023
1.23.5
Nov 13, 2023
1.23.4
Nov 12, 2023
1.23.3
Nov 09, 2023
1.23.2
Nov 09, 2023
1.23.1
Oct 24, 2023
1.23.0
Oct 16, 2023
1.22.6
Sep 16, 2023
1.22.5
Sep 14, 2023
1.22.4
Sep 14, 2023
1.22.3
Sep 14, 2023
1.22.2
Sep 14, 2023
1.22.1
Sep 13, 2023
1.22.0
Sep 13, 2023
1.21.0
Aug 03, 2023
1.21.0b1
Jul 22, 2023
1.21.0b0
Jul 20, 2023
1.20.0
Jun 30, 2023
1.20.0b1
Jun 09, 2023
1.20.0b0
Jun 09, 2023
1.19.2
May 26, 2023
1.19.1
May 22, 2023
1.19.0
May 05, 2023
1.18.1
May 04, 2023
1.18.0
Mar 31, 2023
1.18.0b1
Feb 09, 2023
1.18.0b0
Jan 30, 2023
1.17.0
Jan 19, 2023
1.16.8
Jan 05, 2023
1.16.7
Jan 03, 2023
1.16.6
Dec 27, 2022
1.16.5
Dec 27, 2022
1.16.4
Dec 20, 2022
1.16.3
Dec 19, 2022
1.16.2
Dec 19, 2022
1.16.1
Dec 17, 2022
1.16.0
Dec 17, 2022
1.16.0b3
Dec 01, 2022
1.16.0b2
Dec 01, 2022
1.16.0b1
Nov 30, 2022
1.16.0b0
Nov 28, 2022
1.15.5
Dec 27, 2022
1.15.4
Nov 18, 2022
1.15.3
Nov 10, 2022
1.15.2
Nov 09, 2022
1.15.1
Nov 07, 2022
1.15.0
Nov 05, 2022
1.14.1
Dec 27, 2022
1.14.0
Nov 04, 2022
1.13.1
Oct 26, 2022
1.13.0
Oct 22, 2022
1.12.1
Oct 17, 2022
1.12.0
Oct 06, 2022
1.11.12
Sep 28, 2022
1.11.11
Sep 26, 2022
1.11.10
Sep 20, 2022
1.11.9
Aug 19, 2022
1.11.8
Aug 17, 2022
1.11.7
Aug 02, 2022
1.11.6
Jun 24, 2022
1.11.5
Jun 24, 2022
1.11.4
Jun 13, 2022
1.11.3
Jun 10, 2022
1.11.2
Jun 06, 2022
1.11.1
May 31, 2022
1.11.0
May 06, 2022
1.10.9
May 06, 2022
1.10.8
Apr 13, 2022
1.10.7
Apr 12, 2022
1.10.6
Apr 12, 2022
1.10.5
Apr 11, 2022
1.10.4
Apr 01, 2022
1.10.3
Mar 29, 2022
1.10.2
Mar 28, 2022
1.10.1
Mar 14, 2022
1.10.0
Feb 25, 2022
1.9.2
Feb 22, 2022
1.9.1
Feb 11, 2022
1.9.0
Feb 11, 2022
1.8.13
Feb 10, 2022
1.8.12
Jan 06, 2022
1.8.10
Dec 29, 2021
1.8.9
Dec 23, 2021
1.8.8
Dec 17, 2021
1.8.7
Dec 14, 2021
1.8.6
Dec 13, 2021
1.8.5
Dec 10, 2021
1.8.4
Dec 09, 2021
1.8.3
Dec 08, 2021
1.8.2
Dec 04, 2021
1.8.1
Dec 02, 2021
1.8.0
Nov 29, 2021
1.7.2
Nov 03, 2021
1.7.1
Nov 02, 2021
1.7.0
Oct 12, 2021
1.6.3
Oct 08, 2021
1.6.2
Oct 06, 2021
1.6.1
Oct 06, 2021
1.6.0
Sep 30, 2021
1.5.1
Sep 27, 2021
1.5.0
Sep 27, 2021
1.4.0
Sep 13, 2021
1.3.0
Sep 08, 2021
1.2.8
Sep 01, 2021
1.2.7
Sep 01, 2021
1.2.6
Aug 25, 2021
1.2.5
Jul 21, 2021
1.2.4
Jul 13, 2021
1.2.3
Jul 08, 2021
1.2.2
Jul 06, 2021
1.2.1
Jul 06, 2021
1.2.0
Jun 25, 2021
1.1.6
Jun 21, 2021
1.1.5
Jun 17, 2021
1.1.4
Jun 16, 2021
1.1.3
Jun 15, 2021
1.1.2
Jun 14, 2021
1.1.1
Jun 14, 2021
1.1.0
Jun 02, 2021
1.0.6
Jun 01, 2021
1.0.5
May 25, 2021
1.0.4
May 18, 2021
1.0.3
May 16, 2021
1.0.2
May 16, 2021
1.0.1
May 14, 2021
1.0.0
May 10, 2021
1.0.0b3
May 10, 2021
1.0.0b2
May 07, 2021
1.0.0b1
May 05, 2021
0.4.3
Apr 25, 2021
0.4.2
Apr 20, 2021
0.4.1
Apr 19, 2021
0.4.0
Apr 18, 2021
0.4.0b1
Apr 14, 2021
0.3.4
Apr 09, 2021
0.3.3
Apr 09, 2021
0.3.2
Mar 25, 2021
0.3.1
Mar 21, 2021
0.3.0
Mar 19, 2021
0.2.3
Mar 16, 2021
0.2.2
Mar 16, 2021
0.2.1
Mar 15, 2021
0.2.0
Feb 27, 2021
0.1.1
Feb 24, 2021
0.1.0
Feb 23, 2021
