motor.txt

.. _python-async-driver:

====================
Motor (Async Driver)
====================

.. facet::
   :name: genre
   :values: reference

.. facet::
   :name: programming_language
   :values: python

.. meta::
   :keywords: Python async, Stable API, local connection, atlas, code example
   :description: Explore Motor, the async Python driver for MongoDB, with installation guides, connection examples, and compatibility details.

.. contents:: On this page
   :local:
   :backlinks: none
   :depth: 1
   :class: twocols

.. banner::
   :variant: warning

   As of May 14, 2025, Motor is deprecated in favor of the GA release of the PyMongo Async
   API in the PyMongo library. We will not add new features to Motor, and we will
   provide only bug fixes until it reaches end of life on May 14, 2026. After that, we will
   fix only critical bugs until final support ends on May 14, 2027. We
   strongly recommend migrating to the PyMongo Async API while Motor is still supported.
    
   For more information about migrating, see the `Migrate to PyMongo Async <https://www.mongodb.com/docs/languages/python/pymongo-driver/current/reference/migration/>`__
   guide in the PyMongo documentation.


Introduction
------------

Welcome to the documentation site for Motor, the official MongoDB
driver for asynchronous Python applications. Download it using
`pip <https://pypi.python.org/pypi/pip>`__
or set up a runnable project by following our tutorials.

.. tip::

   If you do not need to access MongoDB in a non-blocking manner or from
   co-routines, we recommend that you use the `PyMongo
   <https://www.mongodb.com/docs/languages/python/pymongo-driver/current/>`__
   driver instead.

- `Tutorial on using Motor with Tornado <http://motor.readthedocs.org/en/stable/tutorial-tornado.html>`__

- `Tutorial on using Motor with asyncio <https://motor.readthedocs.io/en/stable/tutorial-asyncio.html>`__

- `Motor Documentation <http://motor.readthedocs.org/>`__

- `Changelog <http://motor.readthedocs.org/en/stable/changelog.html>`__

- `Source Code <https://github.com/mongodb/motor/>`__

Follow the links below to read blog posts that describe specific use cases
for the Motor driver:

- `Porting From PyMongo To Motor <http://emptysqua.re/blog/porting-from-pymongo-to-motor/>`__

- `Refactoring Tornado Coroutines <http://emptysqua.re/blog/refactoring-tornado-coroutines/>`__

- `All Motor articles on A. Jesse Jiryu Davis's blog <http://emptysqua.re/blog/category/motor/>`__

Installation
------------

You must install the Motor driver module to make it available to your Python
application. We recommend using `pip <http://pypi.python.org/pypi/pip>`__
to install Motor.

The following command demonstrates how you can install the latest version of
the module using the command line:

.. code-block:: sh

   $ python -m pip install motor

For more information on requirements and other methods of installation,
see the `Motor Installation <https://motor.readthedocs.io/en/stable/installation.html>`__
documentation.

.. _connect-atlas-motor-driver:

Connect to MongoDB Atlas
------------------------

You can use the following connection snippet to test your connection to
your MongoDB deployment on Atlas using the ``asyncio`` asynchronous framework:

.. literalinclude:: /includes/connection-snippets/scram/py-motor-connection.py
   :language: python

This connection snippet uses the {+stable-api+} feature, which you can
enable when using the Motor driver v2.5 and later to connect to MongoDB Server
v5.0 and later. When you use this feature, you can update your driver or server without
worrying about backward compatibility issues with any commands covered by the
{+stable-api+}.

To learn more about the {+stable-api+} feature, see
:manual:`{+stable-api+} </reference/stable-api/>` in the Server manual.

.. include:: /includes/stable-api-notice.rst

.. _connect-atlas-no-stable-api-motor-driver:

Connect to MongoDB Atlas Without the Stable API
-----------------------------------------------

If you are using a version of MongoDB or the driver that doesn't support the
{+stable-api+} feature, you can use the following code snippet to test your connection
to your MongoDB deployment on Atlas:

.. literalinclude:: /includes/connection-snippets/scram/py-motor-connection-no-stableapi.py
   :language: python

If you are using the ``tornado`` asynchronous library, you can use the
following code to connect to your MongoDB deployment:

.. literalinclude:: /includes/connection-snippets/scram/py-motor-connection-tornado.py
   :language: python

Connect to a MongoDB Server on Your Local Machine
-------------------------------------------------

.. include:: /includes/localhost-connection.rst

To test whether you can connect to your server, replace the connection
string in the :ref:`Connect to MongoDB Atlas <connect-atlas-motor-driver>` code
example and run it.

Compatibility
-------------

MongoDB Compatibility
~~~~~~~~~~~~~~~~~~~~~

The following compatibility table specifies the recommended version or versions
of the Motor (Python async) driver for use with a specific version of MongoDB.

The first column lists the driver version.

.. sharedinclude:: dbx/lifecycle-schedule-callout.rst

.. include:: /includes/mongodb-compatibility-table-motor.rst

.. include:: /includes/older-server-versions-unsupported.rst

Language Compatibility
~~~~~~~~~~~~~~~~~~~~~~

The following compatibility table specifies the recommended version(s) of the
Motor (Python async) driver for use with a specific version of Python.

The first column lists the driver version(s).

.. include:: /includes/language-compatibility-table-motor.rst

.. include:: /includes/about-driver-compatibility.rst

.. include:: /includes/help-links-motor.rst