Beanie

Warnings

• breaking Beanie v2.0 dropped Motor. Use pymongo AsyncMongoClient instead of AsyncIOMotorClient. Motor-based code breaks with ImportError or unexpected behavior.
  Fix: from pymongo import AsyncMongoClient — not from motor.motor_asyncio import AsyncIOMotorClient
• breaking Inner class Collection removed in v2. Use Settings instead. Collection still referenced in most tutorials and LLM-generated code.
  Fix: class Settings: name = 'collection_name' — not class Collection: name = '...'
• breaking Beanie v2.0 requires Pydantic v2. Pydantic v1 patterns (@validator, class Config) break. See pydantic registry entry for migration.
  Fix: Use @field_validator, model_config = ConfigDict(...) — Pydantic v2 patterns.
• breaking Sync usage removed in beanie. There is no sync version. Use Bunnet (pip install bunnet) for synchronous MongoDB access.
  Fix: pip install bunnet — same API as beanie but sync.
• gotcha init_beanie() must be called before any Document operation. Calling Document.find() or Document.insert() before init raises RuntimeError. Common mistake in FastAPI startup.
  Fix: Call init_beanie() in FastAPI lifespan startup, not at module level.
• gotcha All document models must be passed to init_beanie(document_models=[...]). Missing a model means that model's collection is not configured — operations silently fail or error.
  Fix: List every Document subclass in document_models=[Model1, Model2, ...]
• gotcha allow_index_dropping defaults to False. Indexes are not deleted automatically when removed from model. Old indexes accumulate silently.
  Fix: Pass allow_index_dropping=True to init_beanie() in development to clean up. Leave False in production.

Install

• pip install beanie Python

Imports

• Document + init_beanie

  from pymongo import AsyncMongoClient
  from beanie import Document, Indexed, init_beanie
  from pydantic import BaseModel
  from typing import Optional
  
  class Category(BaseModel):
      name: str
  
  class Product(Document):
      name: str
      price: Indexed(float)
      category: Optional[Category] = None
  
      class Settings:  # v2 style — not Collection
          name = 'products'
  
  async def init():
      client = AsyncMongoClient('mongodb://localhost:27017')
      await init_beanie(
          database=client.mydb,
          document_models=[Product]
      )

  v2.0 dropped Motor. Use pymongo AsyncMongoClient. Inner class Collection removed — use Settings. LLMs trained pre-2025 generate Motor + Collection patterns.
• CRUD operations

  # All operations require init_beanie() to have been called first
  
  # Create
  product = await Product(name='Widget', price=9.99).insert()
  # or:
  product = await Product.insert_one(Product(name='Widget', price=9.99))
  
  # Find
  products = await Product.find(Product.price < 10.0).to_list()
  product = await Product.find_one(Product.name == 'Widget')
  product = await Product.get(product_id)  # by _id
  
  # Update
  await product.set({Product.price: 12.99})
  # or:
  product.price = 12.99
  await product.save()
  
  # Delete
  await product.delete()

  Must call init_beanie() before any Document operation. Query syntax uses Python operators (Product.price < 10.0), not raw MongoDB dicts.

Quickstart

Beanie v2.x quickstart with pymongo AsyncMongoClient.

# pip install beanie
from pymongo import AsyncMongoClient
from beanie import Document, Indexed, init_beanie
from typing import Optional
import asyncio

class Product(Document):
    name: str
    price: Indexed(float)
    in_stock: bool = True

    class Settings:
        name = 'products'  # MongoDB collection name

async def main():
    client = AsyncMongoClient('mongodb://localhost:27017')
    await init_beanie(database=client.shop, document_models=[Product])

    # Insert
    p = await Product(name='Widget', price=9.99).insert()
    print(p.id)  # ObjectId

    # Query
    cheap = await Product.find(Product.price < 20.0).to_list()
    one = await Product.find_one(Product.name == 'Widget')

    # Update
    await one.set({Product.price: 11.99})

    # Delete
    await one.delete()

asyncio.run(main())