Upgrade PyMongo Versions

On this page

Overview

Show Deprecation Warnings
Breaking Changes

Overview

This page describes the changes you must make to your application when you upgrade to a new version of PyMongo.

Important

This guide includes breaking changes to only PyMongo versions after v4.0. If you're upgrading from PyMongo v2 or v3, see the PyMongo 4 Migration Guide.

Before you upgrade, perform the following actions:

Ensure the new PyMongo version is compatible with the MongoDB Server versions your application connects to and the Python version your application runs on. For version compatibility information, see the PyMongo Compatibility page.
Address any breaking changes between the driver version your application is using and your planned upgrade version in the Breaking Changes section.

Tip

To minimize the number of changes your application requires when upgrading driver versions in the future, use the Stable API.

Show Deprecation Warnings

When you use a deprecated PyMongo feature, the driver raises a DeprecationWarning. By default, the Python interpreter silences these warnings. To print them to stderr, start Python with the -Wd options.

The following example runs insert.py, a Python application that calls a deprecated method. The interpreter shows a DeprecationWarning because Python was started with the -Wd options.

$ python3 -Wd insert.py
insert.py:4: DeprecationWarning: insert is deprecated. Use insert_one or insert_many instead.
  client.test.test.insert({})

To treat DeprecationWarning messages as exceptions, start Python with the -We options instead, as shown in the following example:

$ python3 -We insert.py
Traceback (most recent call last):
  File "insert.py", line 4, in <module>
    client.test.test.insert({})
  File "/home/durin/work/mongo-python-driver/pymongo/collection.py", line 2906, in insert
    "instead.", DeprecationWarning, stacklevel=2)
DeprecationWarning: insert is deprecated. Use insert_one or insert_many instead.

Tip

For more information about interpreter warnings and the -W option, see the following Python documentation:

Breaking Changes

A breaking change is a change of a convention or a behavior starting in a specific version of the driver. This type of change may prevent your application from working properly if not addressed before upgrading the driver.

The breaking changes in this section are categorized by the driver version that introduced them. When upgrading driver versions, address all the breaking changes between the current and upgrade versions.

Example

Upgrading from Version 4.0

If you're upgrading PyMongo from v4.0 to v4.7, address all breaking changes listed for versions 4.1 to 4.7, if any.

Version 4.11 Breaking Changes

MongoDB Server v3.6 is no longer supported. The minimum supported MongoDB Server version is now v4.0.
The minimum wire version is now 7. See minWireVersion.

Version 4.9 Breaking Changes

You must use pymongocrypt v1.10 or later to use Client-Side Field Level Encryption (CSFLE) in your application.

Version 4.8 Breaking Changes

Because PyMongo v4.8 uses hatch as its backend build system, you can no longer build the driver by using the setup.py file. Instead, you must install PyMongo by using pip. For editable installations, you must use pip v21.3 or later.

Version 4.7 Breaking Changes

All occurrences of the SON collection type on all internal classes and commands have been changed to dict.
The options.pool_options.metadata property is now of type dict, not SON. The following code example shows the differences in how these formats store data:

# Before (SON)
>>> from pymongo import MongoClient
>>> client = MongoClient()
>>> client.options.pool_options.metadata
SON([('driver', SON([('name', 'PyMongo'), ('version', '4.7.0.dev0')])), ('os', SON([('type', 'Darwin'), ('name', 'Darwin'), ('architecture', 'arm64'), ('version', '14.3')])), ('platform', 'CPython 3.11.6.final.0')])
# After (dict)
>>> client.options.pool_options.metadata
{'driver': {'name': 'PyMongo', 'version': '4.7.0.dev0'}, 'os': {'type': 'Darwin', 'name': 'Darwin', 'architecture': 'arm64', 'version': '14.3'}, 'platform': 'CPython 3.11.6.final.0'}

To convert a single-layer dict object to a SON object, pass the dict object to the SON constructor, as shown in the following example:

>>> data_as_dict = client.options.pool_options.metadata
>>> SON(data_as_dict)
SON([('driver', {'name': 'PyMongo', 'version': '4.7.0.dev0'}), ('os', {'type': 'Darwin', 'name': 'Darwin', 'architecture': 'arm64', 'version': '14.3'}), ('platform', 'CPython 3.11.6.final.0')])

If the dict object has multiple layers, you must convert the values one at a time, as shown in the following example:

>>> def dict_to_SON(data_as_dict: dict[Any, Any]):
...     data_as_SON = SON()
...     for key, value in data_as_dict.items():
...         data_as_SON[key] = dict_to_SON(value) if isinstance(value, dict) else value
...     return data_as_SON
>>>
>>> dict_to_SON(data_as_dict)
SON([('driver', SON([('name', 'PyMongo'), ('version', '4.7.0.dev0')])), ('os', SON([('type', 'Darwin'), ('name', 'Darwin'), ('architecture', 'arm64'), ('version', '14.3')])), ('platform', 'CPython 3.11.6.final.0')])

Version 4.2 Breaking Changes

To improve support for the Pyright tool, the ClientSession class no longer uses generic typing.
pymongocrypt v1.3.0 or later is required for Client-Side Field Level Encryption (CSFLE).
The bson, pymongo, and gridfs packages now use the __all__ variable to declare their public APIs. If your application contains a from bson import * statement, ensure that it still imports the necessary APIs.
The estimated_document_count() method always uses the count command. This command is not available in the Stable API in MongoDB versions 5.0.0 through 5.0.8. If you use the estimated_document_count() method with the Stable API, you must either upgrade to MongoDB Server v5.0.9 or later, or set the pymongo.server_api.ServerApi.strict option to False.

Back

What's New

Migrate from Motor