{"id":21748,"library":"pydantic-mongo","title":"Pydantic Mongo","description":"A document object mapper (ODM) for Pydantic and PyMongo, allowing you to define MongoDB document schemas with Pydantic models and perform CRUD operations with an optional repository pattern. Current version: 3.1.0 (released 2025-04-18). Active development with frequent minor releases.","status":"active","version":"3.1.0","language":"python","source_language":"en","source_url":"https://github.com/jefersondaniel/pydantic-mongo","tags":["mongo","mongodb","pydantic","odm","orm","pymongo","document-mapper"],"install":[{"cmd":"pip install pydantic-mongo","lang":"bash","label":"Install from PyPI"}],"dependencies":[{"reason":"Core dependency for model definition","package":"pydantic","optional":false},{"reason":"MongoDB driver","package":"pymongo","optional":false}],"imports":[{"note":"ObjectIdField is a custom field type provided by pydantic-mongo, not Pydantic's ObjectId.","wrong":"from pydantic.fields import ObjectId","symbol":"ObjectIdField","correct":"from pydantic_mongo import ObjectIdField"},{"note":"AbstractRepository is exported at the package level since v2.4.0.","wrong":"from pydantic_mongo.repository import AbstractRepository","symbol":"AbstractRepository","correct":"from pydantic_mongo import AbstractRepository"},{"note":"Introduced in v2.4.0.","symbol":"AsyncAbstractRepository","correct":"from pydantic_mongo import AsyncAbstractRepository"}],"quickstart":{"code":"import os\nfrom pydantic import BaseModel\nfrom pydantic_mongo import PydanticMongo\n\nclass User(BaseModel):\n    name: str\n    email: str\n\nmongo = PydanticMongo(connection_string=os.environ.get('MONGO_URI', 'mongodb://localhost:27017'))\ndb = mongo.get_database('myapp')\ncollection = mongo.get_collection('users', model=User)\nuser = User(name='John', email='john@example.com')\ninserted_id = collection.insert_one(user)\nprint(f'Inserted user with id: {inserted_id}')","lang":"python","description":"Basic usage: define a Pydantic model, connect to MongoDB, and insert a document."},"warnings":[{"fix":"Upgrade to v3.x and update any code that relied on ObjectId being returned as an ObjectId object. Use pymongo's ObjectId constructor if needed: from bson import ObjectId; ObjectId(str_id).","message":"In v3.0.0, ObjectId serialization changed to return a string instead of an ObjectId instance. This affects how ObjectIdField values are returned from queries and must be handled when comparing IDs or passing to functions expecting ObjectId.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Use Pydantic v2 models (from pydantic import BaseModel). If you must use v1, stick with pydantic-mongo <2.0.0.","message":"Pydantic v2 vs v1: pydantic-mongo is built on Pydantic v2. If you use Pydantic v1 models, you may encounter validation errors or compatibility issues.","severity":"gotcha","affected_versions":">=2.0.0"},{"fix":"Always call mongo.get_collection('collection_name', model=MyModel).","message":"You must pass the model class to get_collection() when using custom Pydantic models; otherwise, the collection operates on raw dicts.","severity":"gotcha","affected_versions":"all"}],"env_vars":null,"last_verified":"2026-04-27T00:00:00.000Z","next_check":"2026-07-26T00:00:00.000Z","problems":[{"fix":"Upgrade to latest version with pip install --upgrade pydantic-mongo and use the correct import: from pydantic_mongo import ObjectIdField.","cause":"Outdated version (<2.0.0) or incorrect import path.","error":"ImportError: cannot import name 'ObjectIdField' from 'pydantic_mongo'"},{"fix":"Assign the result of get_collection() to a variable: collection = mongo.get_collection(...).","cause":"get_collection() was called with a collection name as a plain string instead of the actual collection object.","error":"AttributeError: 'str' object has no attribute 'insert_one'"},{"fix":"Define the field with ObjectIdField(default=None) or use Optional[ObjectIdField] to allow null values.","cause":"Setting an ObjectIdField to None. ObjectIdField does not allow None by default.","error":"TypeError: ObjectIdField only supports assigning ObjectId or strictly string typed values, not <class 'NoneType'>"},{"fix":"Let the library auto-generate IDs. If you must set it manually, ensure it is a valid ObjectId string or ObjectId instance. For new documents, omit the id field entirely.","cause":"ObjectIdField is required but not provided when creating a new model. ObjectIdField is automatically generated by the library, but if you set it manually to an invalid value, validation fails.","error":"pydantic_core._pydantic_core.ValidationError: 1 validation error for User id"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}