Motor (Async MongoDB)

3.7.1 verified Tue May 12 auth: no python install: verified quickstart: stale deprecated

DEPRECATED as of May 14, 2025. Motor was the official async Python driver for MongoDB. Superseded by the native AsyncMongoClient in pymongo >= 4.13 (GA). EOL: May 14, 2026. Critical bug fixes only until May 14, 2027. No new features. Current version: 3.7.1. Requires PyMongo 4.9+. For new projects use pymongo's AsyncMongoClient instead.

pip install pymongo

Common errors

error ImportError: cannot import name '_QUERY_OPTIONS' from 'pymongo.cursor' ↓

cause This error occurs due to an incompatibility between the installed `motor` version and the `pymongo` version, where `motor` is trying to import an internal `pymongo` symbol that has been removed or renamed in newer `pymongo` releases.

fix

Upgrade motor to version 3.6.0 or higher, which is compatible with PyMongo >= 4.9. Alternatively, if you must use an older motor (<3.6), pin your pymongo version to <4.9 (e.g., pymongo==4.8.0).

error pymongo.errors.ServerSelectionTimeoutError ↓

cause This error indicates that the Motor client could not connect to the MongoDB server within the specified timeout period, often due to network issues, incorrect connection string, or the MongoDB server not running or being inaccessible.

fix

Verify that your MongoDB server is running and accessible from the application's environment, check the connection string for correctness (including host, port, authentication), and ensure network access rules (e.g., firewalls, security groups, MongoDB Atlas IP whitelist) allow connections. You can also increase serverSelectionTimeoutMS in the client constructor if the network is slow.

error TypeError: Object of type ObjectId is not JSON serializable ↓

cause MongoDB documents contain BSON types like `ObjectId` that are not natively recognized by Python's standard `json` library, leading to a `TypeError` when attempting to serialize a document directly to JSON for API responses.

fix

Before returning MongoDB documents as JSON, convert the ObjectId fields (and other BSON types like datetime) to strings. This can be done manually or by using bson.json_util.dumps for comprehensive serialization of MongoDB types.

error NotImplementedError: __bool__ ↓

cause In Motor 3.0 and later, directly evaluating a `MotorDatabase` instance in a boolean context (e.g., `if database:`) raises this error, as the boolean conversion behavior was removed.

fix

Explicitly compare the MotorDatabase instance with None if you intend to check if it's been initialized (e.g., if database is not None:).

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.

breaking PyMongo's AsyncMongoClient failed to resolve SRV record DNS. This `DNS query name does not exist` error often indicates an incorrect MongoDB connection string (especially `mongodb+srv://` URIs) or a network issue preventing DNS resolution for the specified MongoDB host. ↓

fix Verify the MongoDB connection string is correctly formatted and accessible. Ensure your environment has proper network access to a DNS server that can resolve SRV records for your MongoDB host. Check for typos in the hostname or issues with firewalls/proxy settings.

breaking Connecting to MongoDB Atlas via SRV record (mongodb+srv://) fails with `pymongo.errors.ConfigurationError: The DNS query name does not exist`. This indicates an issue with the MongoDB connection URI or the network's ability to resolve SRV DNS records for the specified hostname. ↓

fix Verify the MongoDB Atlas connection string is correct and accessible. Ensure the network environment allows DNS resolution for SRV records (e.g., firewall rules, VPN configuration). Test DNS resolution manually for the SRV record (e.g., `dig SRV _mongodb._tcp.yourcluster.mongodb.net`).

Install

pip install motor

Install compatibility verified last tested: 2026-05-12

python os / libc variant status wheel install import disk

3.10 alpine (musl) motor - - 0.28s 26.3M

3.10 alpine (musl) pymongo - - 0.28s 79.7M

3.10 slim (glibc) motor - - 0.21s 28M

3.10 slim (glibc) pymongo - - 0.22s 148M

3.11 alpine (musl) motor - - 0.46s 29.7M

3.11 alpine (musl) pymongo - - 0.45s 87.7M

3.11 slim (glibc) motor - - 0.37s 32M

3.11 slim (glibc) pymongo - - 0.36s 157M

3.12 alpine (musl) motor - - 0.60s 21.3M

3.12 alpine (musl) pymongo - - 0.60s 78.6M

3.12 slim (glibc) motor - - 0.57s 25M

3.12 slim (glibc) pymongo - - 0.57s 149M

3.13 alpine (musl) motor - - 0.63s 20.9M

3.13 alpine (musl) pymongo - - 0.59s 75.1M

3.13 slim (glibc) motor - - 0.55s 25M

3.13 slim (glibc) pymongo - - 0.56s 149M

3.9 alpine (musl) motor - - 0.26s 25.7M

3.9 alpine (musl) pymongo - - 0.26s 78.7M

3.9 slim (glibc) motor - - 0.24s 27M

3.9 slim (glibc) pymongo - - 0.22s 147M

Imports

AsyncMongoClient (recommended — pymongo native)

wrong

import motor.motor_asyncio
client = motor.motor_asyncio.AsyncIOMotorClient('mongodb+srv://...')

correct

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)

wrong

import motor
client = motor.MongoClient(...)  # wrong — must use motor.motor_asyncio

correct

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

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