Migrate to PyMongo Async

On this page

Overview

Synchronous Versus Asynchronous
Migrate From Motor
Method Signature Changes
Migrate from PyMongo
Asynchronous Methods
Additional Information

Important

The PyMongo Async driver is experimental and should not be used in production environments. Classes, methods, and behaviors described in this guide might change prior to the full release. If you encounter any issues with PyMongo Async, you can learn how to report them on the Issues & Help page.

Overview

The PyMongo Async driver is a unification of PyMongo and the Motor library. In this guide, you can identify the changes you must make to migrate an application from PyMongo or Motor to the PyMongo Async driver.

Synchronous Versus Asynchronous

To determine whether to migrate to the PyMongo Async driver or to continue using Synchronous PyMongo, consider the information in this section.

Synchronous PyMongo is preferable if the following criteria applies to your application or use case:

Your application is simple in execution, or you prefer to avoid using asynchronous calls in your code
Your application relies on serial workloads or workloads with very fast response times
You prefer the simplicity of synchronous logic when debugging your application

Consider migrating to the PyMongo Async driver if the following criteria applies to your application or use case:

Your application implements large, highly concurrent workloads (on the order of thousands of concurrent operations)
Your application relies on workloads that spend a long time waiting for responses or writing data
Your application relies on other asynchronous libraries or frameworks, such as FastAPI

Migrate From Motor

Warning

Motor Deprecation

Motor will be deprecated one year after the production release of the PyMongo Async driver. We strongly recommend that Motor users migrate to the PyMongo Async driver while Motor is still supported.

The PyMongo Async driver functions similarly to the Motor library, but allows for improved latency and throughput due to directly using Python Asyncio instead of delegating work to a thread pool. In most cases, you can directly migrate existing Motor applications to PyMongo Async by using AsyncMongoClient in place of MotorClient, and changing the application's import statements to import from pymongo.

The following example shows the difference in imports to use a client for read and write operations in Motor compared to PyMongo Async:

# Motor client import
from motor.motor_asyncio import AsyncIOMotorClient
# PyMongo Async client import
from pymongo import AsyncMongoClient

To see a list of the asynchronous methods available in the PyMongo Async driver, see the Asynchronous Methods section. To learn about the versions of Motor that correspond to PyMongo, see the Motor Compatibility section of the Compatibility guide.

The following section shows the method signature changes that you must implement in your application when migrating from Motor to the PyMongo Async driver.

Warning

The PyMongo Async driver does not support Tornado.

Method Signature Changes

The following Motor method signatures behave differently in the PyMongo Async driver:

AsyncMongoClient.__init__() does not accept an io_loop parameter.
AsyncCursor.each() does not exist in the PyMongo Async driver.
MotorGridOut.stream_to_handler() does not exist in the PyMongo Async driver.
AsyncCursor.to_list(0) is not valid in the PyMongo Async driver. Use to_list(None) instead.
MongoClient is thread safe and can be used by many threads, however, an AsyncMongoClient is not thread safe and should only be used by a single event loop.

Warning

Motor users may experience a degradation of performance when switching to the PyMongo Async driver. This is due to the PyMongo Async driver using native asyncio tasks instead of thread-based executors. Thread-based executors have similar performance characteristics to the synchronous driver, but slower. This means they perform better for workloads that do not fit the preceding criteria for the PyMongo Async driver.

If you are experiencing performance slowdown, identify whether the PyMongo Async driver is necessary for your usecase. If you determine your use case is better served by synchronous PyMongo, consider using the synchronous driver with asyncio.loop.run_in_executor() for asynchronous compatibility. To learn more, see the Event Loop API documentation.

Migrate from PyMongo

The PyMongo Async driver behaves similarly to PyMongo, but all methods that perform network operations are coroutines and must be awaited. To migrate from PyMongo to PyMongo Async, you must update your code in the following ways:

Replace all uses of MongoClient with AsyncMongoClient.
Add the await keyword to all asynchronous method calls.
If you call an asynchronous method inside a function, mark the function as async.

Keep the following points in mind when migrating from synchronous PyMongo to the PyMongo Async driver:

To convert an AsyncCursor to a list, you must use the asynchronous cursor.to_list() method.
The AsyncCollection.find() method in the PyMongo Async driver is synchronous, but returns an AsyncCursor. To iterate through the cursor, you must use an async for loop.
The AsyncMongoClient object does not support the connect keyword argument.
You cannot share AsyncMongoClient objects across threads or event loops.
To access a property or method of a result returned by an asynchronous call, you must properly wrap the call in parentheses, as shown in the following example:
```
id = (await posts.insert_one(doc)).inserted_id
```

Asynchronous Methods

For a complete list of asynchronous methods available in the PyMongo Async driver, see the API documentation.

Note

Any methods not listed in the preceding API documentation are synchronous.

Additional Information

To learn more about asynchronous Python, see the Python Asyncio documentation.

Back

Upgrade Guides

Previous Versions