Motor (Async MongoDB)

Warnings

• breaking Motor deprecated May 14, 2025. EOL May 14, 2026. No new features. Bug fixes only. Migrate to pymongo AsyncMongoClient.
  Fix: Replace motor.motor_asyncio.AsyncIOMotorClient with pymongo.AsyncMongoClient. API is nearly identical.
• breaking Motor < 3.6 is incompatible with PyMongo >= 4.9. Version mismatch causes ImportError or unexpected failures.
  Fix: Upgrade to Motor >= 3.6 if staying on motor. Or migrate to pymongo AsyncMongoClient.
• gotcha Import path is motor.motor_asyncio.AsyncIOMotorClient — not motor.AsyncIOMotorClient. LLMs frequently drop the motor_asyncio submodule.
  Fix: from motor.motor_asyncio import AsyncIOMotorClient — not from motor import AsyncIOMotorClient
• gotcha Motor does NOT use true async I/O — it uses a thread pool under the hood. In high-concurrency scenarios this can cause performance degradation. pymongo's AsyncMongoClient uses true asyncio.
  Fix: Migrate to pymongo AsyncMongoClient for true async I/O performance.
• gotcha Motor cursor iteration requires 'async for' not 'for'. Sync iteration over MotorCursor silently returns zero results instead of raising an error.
  Fix: async for doc in collection.find({}): print(doc)
• gotcha Python 3.8 dropped in motor 3.7. Python 3.9 dropped in motor 3.8. Check compatibility matrix before upgrading.
  Fix: Use Python 3.10+ for latest motor versions.

Install

• pip install pymongo Python (use this — native AsyncMongoClient)
• pip install motor Python (deprecated — EOL May 2026)

Imports

• AsyncMongoClient (recommended — pymongo native)

  from pymongo import AsyncMongoClient
  import asyncio
  
  async def main():
      client = AsyncMongoClient('mongodb+srv://user:pass@cluster.mongodb.net/')
      db = client['mydb']
      result = await db['users'].insert_one({'name': 'Alice'})
      print(result.inserted_id)
      await client.close()
  
  asyncio.run(main())

  Motor is deprecated. Use AsyncMongoClient from pymongo >= 4.13 for new projects. API is nearly identical — same await patterns, same collection methods.
• AsyncIOMotorClient (motor — existing code)

  import motor.motor_asyncio
  import asyncio
  
  async def main():
      client = motor.motor_asyncio.AsyncIOMotorClient(
          'mongodb+srv://user:pass@cluster.mongodb.net/'
      )
      db = client['mydb']
      result = await db['users'].insert_one({'name': 'Alice'})
      print(result.inserted_id)
  
  asyncio.run(main())

  Import is motor.motor_asyncio.AsyncIOMotorClient — not motor.MongoClient or motor.AsyncIOMotorClient directly. The motor_asyncio submodule is required.

Quickstart

Async MongoDB using pymongo's native AsyncMongoClient (replaces motor).

# New projects: use pymongo's native async instead of motor
# pip install 'pymongo[srv]'
from pymongo import AsyncMongoClient
import asyncio

async def main():
    client = AsyncMongoClient('mongodb+srv://user:pass@cluster.mongodb.net/')
    db = client['mydb']
    col = db['users']

    # All same methods as sync pymongo but with await
    await col.insert_one({'name': 'Alice', 'age': 30})
    doc = await col.find_one({'name': 'Alice'})
    print(doc)
    await col.update_one({'name': 'Alice'}, {'$set': {'age': 31}})
    count = await col.count_documents({})
    print(count)
    await client.close()

asyncio.run(main())