Install & Compatibility
Where this runs
tested against v1.1.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.872s · 36.8MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 4.4s · import 0.832s · 38MB
37MB installed
● package 37MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Model
✓ from odmantic import Model
✗ from pydantic import BaseModel
ODMantic models must inherit from odmantic.Model, not BaseModel, to enable MongoDB persistence.
Field
✓ from odmantic import Field
✗ from pydantic import Field
Use ODMantic's Field for model fields; it wraps Pydantic's Field but adds ODM-specific features.
ObjectId
✓ from odmantic import ObjectId
✗ from bson import ObjectId
ODMantic provides its own version of ObjectId that integrates with its model system.
Creates a Player model, saves an instance to MongoDB, and retrieves it.
import asyncio
from odmantic import AIOEngine, Model, Field
from motor.motor_asyncio import AsyncIOMotorClient
class Player(Model):
name: str
level: int = Field(default=1)
async def run():
client = AsyncIOMotorClient(os.environ.get('MONGODB_URI', 'mongodb://localhost:27017'))
engine = AIOEngine(motor_client=client, database='test')
player = Player(name='Alice', level=5)
await engine.save(player)
print(f"Saved player with id: {player.id}")
found = await engine.find_one(Player, Player.name == 'Alice')
print(found)
client.close()
asyncio.run(run())
Errors
Common errors & fixes
AttributeError: 'AIOEngine' object has no attribute 'save'
In older versions (<0.7), 'save' was a method on the Engine instance. After refactoring, it's still a method, but the error may occur if a typo or using a wrong object.
fixEnsure you're using the AIOEngine correctly: `await engine.save(instance)`. Verify you have installed ODMantic >=0.7.
pydantic.errors.PydanticUserError: Cannot use `Field` from pydantic inside an ODMantic model
Using `from pydantic import Field` instead of `from odmantic import Field`.
fixChange the import to: `from odmantic import Field`
TypeError: 'coroutine' object does not support item assignment
Forgetting to await an async engine call (e.g., `engine.find_one(...)` returns a coroutine, not the result).
fixAdd `await` before the engine call: `player = await engine.find_one(...)`
Upgrade
Version history
1.1.0latest on PyPI · released Jan 24, 2026
Audit
Dependencies
motorrequiredAsync MongoDB driver; required at runtime
pydanticrequiredData validation and settings management; required at runtime