Motor: the async MongoDB driver that is being retired in favour of PyMongo Async

What Motor solves, and who it was written for

PyMongo is a blocking driver. Every find, insert or aggregate call occupies the thread that issued it until the server replies. In a Tornado or asyncio service that thread is the event loop, so a single slow query stalls every other coroutine waiting on it. Motor exists to close that gap. It presents the same MongoDB operations as coroutines, so a query yields control back to the loop while the network round trip is in flight.

The intended audience is narrow and specific: Python developers running Tornado or asyncio servers against MongoDB, on Unix including macOS, or on Windows. The README lists PyMongo >=4.9,<5 and Python 3.10+ as hard requirements. It is not a general-purpose database abstraction, and it does not try to be an ORM. If your application is synchronous, or threaded, PyMongo is the simpler answer and Motor adds nothing.

One caveat hangs over all of this. The README carries a warning dated 2025-05-14 stating that Motor is deprecated in favour of the GA release of the PyMongo Async API. The stated policy is that no new features will be added, bug fixes continue until end of life on 2026-05-14, and after that only critical bug fixes until final support ends on 2027-05-14. The last push to the repository was on 2026-09-28, which is consistent with maintenance rather than feature work.

How the coroutine layer sits on top of PyMongo

Motor is not a wire-protocol implementation. The dependency list makes that explicit: requirements.txt contains a single line, pymongo>=4.9,<5.0. Motor wraps PyMongo and runs its blocking calls off the event loop, which is why the repository carries a directory named synchro/ alongside motor/ and test/. That directory name is a direct hint about the mechanism: the synchronous PyMongo objects are driven from a separate execution context and their results are handed back to the calling coroutine.

The practical consequence is that Motor inherits PyMongo's behaviour almost entirely. BSON handling, GridFS, client-side field level encryption, authentication mechanisms and wire protocol compression all come from PyMongo, and the optional extras in the README map one-to-one onto PyMongo's own extras: gssapi, aws, ocsp, snappy, srv, zstd and encryption. When you file a bug, the README asks you to report the Motor version, the PyMongo version, whether PyMongo has the C extension, and the Tornado version if relevant. That reporting checklist is itself a description of the architecture. Most defects live in one of those two layers, and the maintainers need to know which.

This design also explains the deprecation. If Motor is a coroutine shim over PyMongo, then adding native async support to PyMongo removes the reason for the shim to exist. The README points to a Migrate to PyMongo Async guide rather than describing the transition itself.

Installing Motor and running a first query

Installation is a single pip command. The README gives no virtualenv or system-package prerequisite beyond Python 3.10 or newer.

pip install motor

If you need a specific authentication or transport feature, install the matching extra. For example, mongodb+srv:// connection strings need the srv extra, and MONGODB-AWS authentication needs aws.

pip install "motor[srv]"

The README also lists a combined command for pulling in every optional dependency at once.

pip install "motor[gssapi,aws,ocsp,snappy,srv,zstd,encryption]"

Motor's own documentation does not inline a worked example in the README. It points to the examples section on ReadTheDocs, and the repository keeps a test/ directory that the README says is exercised with python setup.py test. That is the honest first step: read the examples page, then run the test suite locally to confirm your Python and PyMongo combination behaves as expected before wiring Motor into an application.

When reporting a problem, the README asks for exact versions rather than approximations. These three commands produce the output the maintainers want.

python -c "import sys; print(sys.version)"
python -c "import motor; print(motor.version)"
python -c "import pymongo; print(pymongo.version); print(pymongo.has_c())"

The deprecation is the limitation that matters most

The obvious technical limitation is the one the README states outright. Motor is deprecated. No new features will be added. Bug fixes run until 2026-05-14, critical bug fixes only until 2027-05-14, and then support ends. Any team planning a service with a multi-year horizon is planning past the end of Motor's life, and the README says so in a warning block rather than burying it.

The second limitation is the shim itself. Because Motor drives blocking PyMongo calls off the loop, it carries an extra layer that a native async driver does not need. That does not make it slow in absolute terms, and the README quotes a user describing high-throughput production use, but it does mean the failure surface includes both libraries. When something goes wrong at the boundary, you are debugging two stacks.

There is also a reporting friction that the README makes plain. Issues do not go to GitHub. They go to a JIRA project called MOTOR, and you need an account. If your team's workflow assumes GitHub issues and pull requests, the contribution path is different from what you expect, and the README explicitly asks people not to email the developers directly.

Finally, Motor is the wrong tool for anything synchronous. If your application is a Django view, a Celery worker, or a plain script, the coroutine API buys you nothing and costs you an event loop.

PyMongo Async is the replacement, and it is not just a rename

The alternative named in the README is the PyMongo Async API, which reached GA and prompted Motor's deprecation on 2025-05-14. The difference in approach is structural rather than cosmetic. Motor is a separate package that layers coroutine support over PyMongo; the PyMongo Async API puts async support inside PyMongo itself. One dependency instead of two, one version to track, and no shim boundary between the coroutine layer and the blocking calls underneath.

For anyone starting fresh, that difference decides the question. Installing PyMongo and using its async interface removes a dependency that the maintainers have already committed to retiring. For existing Motor code, the choice is between migrating now while Motor is still receiving bug fixes or migrating later under time pressure. The README links a dedicated migration guide at mongodb.com rather than summarising the changes, which suggests the API differences are substantial enough to need a document.

One thing the README does not do is give a side-by-side code comparison. It does not show a Motor call and its PyMongo Async equivalent. Anyone estimating migration effort has to read the guide and map their own call sites, because the repository material does not quantify the change.

Maintenance, licensing and what upgrading costs

The repository is not archived, and the last push was on 2026-09-28. That is consistent with a project in bug-fix mode: the README's own warning says no new features will be added. The most recent release listed is 3.7.1 from 2025-05-14, the same date as the deprecation notice, with 3.7.0 in January 2025 and 3.6.1 earlier that month. Release cadence slowed to nothing after the deprecation, which matches the stated policy.

Upgrading within Motor is bounded by the dependency constraint. Motor requires PyMongo >=4.9,<5, so a Motor upgrade cannot pull in a PyMongo 5.x release. Python 3.10 is the floor, and the classifiers list support through 3.14. If you are on an older Python, upgrading Motor is not the blocker; upgrading Python is.

Licensing is Apache-2.0, declared both in the repository and in the pyproject.toml classifiers as "License :: OSI Approved :: Apache Software License". Apache-2.0 is permissive and includes an explicit patent grant, which matters for some corporate review processes. It is not a copyleft licence, so it does not impose source-disclosure obligations on your application. Whether that fits your organisation's policy is a question for your legal team, not something this description can settle.

The repository also ships an sbom.json file at the top level, which is useful if your supply-chain process requires a software bill of materials. Combined with the single-line requirements.txt, auditing what Motor pulls in is straightforward.

Editorial conclusion

Adopt Motor only if you already run it or you are pinned to a codebase that cannot move yet, and treat the migration to the PyMongo Async API as scheduled work rather than a someday task. Do not start a new asyncio service on Motor, because the README states no new features will be added and support ends on 2027-05-14. Before committing either way, run pip install motor in a throwaway environment, check that pymongo resolves to a 4.9.x or later 4.x release, and read the Migrate to PyMongo Async guide linked from the README to see how much of your call sites change.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. mongodb/motor on GitHub
3. Project website
4. README
5. Releases