PyMongo

Warnings

• breaking collection.insert() removed in v4.0. Raises AttributeError. LLMs trained on pre-2022 data consistently generate insert() calls.
  Fix: insert_one({'key': 'value'}) or insert_many([{...}, {...}])
• breaking collection.update() removed in v4.0. Raises AttributeError.
  Fix: update_one(filter, update) or update_many(filter, update)
• breaking collection.remove() removed in v4.0. Raises AttributeError.
  Fix: delete_one(filter) or delete_many(filter)
• breaking collection.count() removed in v4.0. Raises AttributeError.
  Fix: count_documents(filter) — note: count_documents({}) counts all docs. estimated_document_count() for fast approximate count.
• breaking collection.save() removed in v4.0.
  Fix: insert_one() for new docs, replace_one(filter, doc, upsert=True) for upsert.
• breaking collection.find_and_modify() removed in v4.0.
  Fix: find_one_and_update(), find_one_and_replace(), or find_one_and_delete()
• gotcha mongodb+srv:// connection strings require dnspython. 'pip install pymongo' alone raises ConfigurationError. Install with pip install 'pymongo[srv]'.
  Fix: pip install 'pymongo[srv]'
• gotcha Motor (async MongoDB) and PyMongo >= 4.9 version coupling. Motor < 3.6 is incompatible with PyMongo >= 4.9. Mixing versions causes ImportError or unexpected behavior.
  Fix: Use Motor >= 3.6 with PyMongo >= 4.9. Or use native AsyncMongoClient (GA in 4.13) instead of Motor.
• gotcha Python 3.8 dropped in PyMongo 4.11. Python 3.9 is now minimum.
  Fix: Use Python 3.9+
• deprecated datetime.utcnow() pattern for MongoDB timestamps deprecated in Python 3.12. Use datetime.now(tz=timezone.utc) instead.
  Fix: from datetime import datetime, timezone; datetime.now(tz=timezone.utc)

Install

• pip install pymongo Python (sync)
• pip install 'pymongo[srv]' Python (with DNS SRV support for mongodb+srv://)

Imports

• MongoClient

  from pymongo import MongoClient
  
  client = MongoClient('mongodb+srv://user:pass@cluster.mongodb.net/')
  db = client['mydb']
  collection = db['users']
  
  # Insert
  result = collection.insert_one({'name': 'Alice', 'age': 30})
  print(result.inserted_id)
  
  # Find
  doc = collection.find_one({'name': 'Alice'})
  
  # Update
  collection.update_one({'name': 'Alice'}, {'$set': {'age': 31}})
  
  # Count
  count = collection.count_documents({'age': {'$gt': 18}})
  
  # Delete
  collection.delete_one({'name': 'Alice'})

  insert(), update(), remove(), save(), count() all removed in v4.0. Use insert_one/insert_many, update_one/update_many, delete_one/delete_many, count_documents instead.
• AsyncMongoClient (v4.13+ GA)

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

  AsyncMongoClient is now part of pymongo natively (GA in v4.13). Motor still works but native async is preferred for new projects.

Quickstart

Minimal pymongo 4.x CRUD operations.

# pip install 'pymongo[srv]'
from pymongo import MongoClient

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

# Insert
col.insert_one({'name': 'Alice', 'age': 30})

# Find
for doc in col.find({'age': {'$gt': 18}}):
    print(doc)

# Update
col.update_one({'name': 'Alice'}, {'$set': {'age': 31}})

# Count
print(col.count_documents({}))

# Delete
col.delete_one({'name': 'Alice'})

client.close()