Beanie

Common errors

Warnings

Install compatibility verified last tested: 2026-05-12

Imports

• Document + init_beanie
  wrong

  from motor.motor_asyncio import AsyncIOMotorClient  # v2: motor no longer needed
  from beanie import Document, init_beanie
  
  class Product(Document):
      name: str
      class Collection:  # removed in v2 — use Settings
          name = 'products'
  
  client = AsyncIOMotorClient('mongodb://localhost')
  await init_beanie(database=client.mydb, document_models=[Product])

  correct

  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
  wrong

  # Calling before init_beanie() raises RuntimeError
  product = await Product.find_one({'name': 'Widget'})

  correct

  # 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 stale last tested: 2026-04-23

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