beanie

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())

Release files for beanie 2.2.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for beanie 2.2.0
File	Size	Uploaded
beanie-2.2.0.tar.gz	70.1 kB	Aug 7, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for beanie 2.2.0
File	Interpreter	ABI	Platform	Reset
beanie-2.2.0-py3-none-any.whl 93.1 kB Aug 7, 2026	Python 3	none	any	Details

Total release size: 163.2 kB

Release files / beanie-2.2.0.tar.gz

Download URL	beanie-2.2.0.tar.gz
Size	70.1 kB
Tags	Source
SHA-256 checksum How to use checksums	`2dc116e7f4a6650f8066f95851d34d898983af6ffaf5366dcfef892993537a51`
BLAKE2b-256 checksum How to use checksums	`6ba14abc93d5437999c55465f68c3c81e4735cdfe22827072c0e9cab00f63d11`
Upload date	Aug 7, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/BeanieODM/beanie
Publishing commit: github.com/BeanieODM/beanie/tree/aa290b5739b52c7f62e43e37724b63038d1e5a81

Workflow

Publishing configuration: github.com/BeanieODM/beanie/blob/aa290b5739b52c7f62e43e37724b63038d1e5a81/.github/workflows/github-actions-publish-project.yml
Publishing logs: github.com/BeanieODM/beanie/actions/runs/31201397950/attempts/1

Artifact

Subject: beanie-2.2.0.tar.gz
SHA-256 checksum: 2dc116e7f4a6650f8066f95851d34d898983af6ffaf5366dcfef892993537a51 Verifying attestations

Release files / beanie-2.2.0-py3-none-any.whl

Download URL	beanie-2.2.0-py3-none-any.whl
Size	93.1 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`4074f893ef00c52b8538b814c9dfd55130eea4ed0579abfae72853657c9029e4`
BLAKE2b-256 checksum How to use checksums	`c5ae2584fb9871b58f3c5334110f8ce00bd1421fe5fbda28eeac9a8d01d10ba6`
Upload date	Aug 7, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/BeanieODM/beanie
Publishing commit: github.com/BeanieODM/beanie/tree/aa290b5739b52c7f62e43e37724b63038d1e5a81

Workflow

Publishing configuration: github.com/BeanieODM/beanie/blob/aa290b5739b52c7f62e43e37724b63038d1e5a81/.github/workflows/github-actions-publish-project.yml
Publishing logs: github.com/BeanieODM/beanie/actions/runs/31201397950/attempts/1

Artifact

Subject: beanie-2.2.0-py3-none-any.whl
SHA-256 checksum: 4074f893ef00c52b8538b814c9dfd55130eea4ed0579abfae72853657c9029e4 Verifying attestations