How to Use Python with MongoDB

Python, the top programming language for data science, and MongoDB, with its flexible and dynamic schema, are a fantastic match for building modern web applications, JSON APIs, data processors, just to name a few. MongoDB has a native Python driver and a team of engineers dedicated to making sure MongoDB and Python work together flawlessly.

Table of Contents

What Is Python?

Python, the Swiss Army knife of today’s dynamically typed languages, has comprehensive support for common data manipulation and processing tasks. Python’s native dictionary and list data types make it second only to JavaScript for manipulating JSON documents – and well-suited to working with BSON. PyMongo, the standard MongoDB driver library for Python, is easy to use and offers an intuitive API for accessing databases, collections, and documents.

Objects retrieved from MongoDB through PyMongo are compatible with dictionaries and lists, so we can easily manipulate, iterate, and print them.

How MongoDB stores data

MongoDB stores data in JSON-like documents:

# Mongodb document (JSON-style)
document_1 = {
"_id" : "BF00001CFOOD",
"item_name" : "Bread",
"quantity" : 2,
"ingredients" : "all-purpose flour"

Python dictionaries look like:

# python dictionary
dict_1 = {
"item_name" : "blender",
"max_discount" : "10%",
"batch_number" : "RR450020FRG",
"price" : 340

Read on for an overview of how to get started and deliver on the potential of this powerful combination.


Download and install Python on your machine (in this screenshot: Windows. You'll notice a slight formatting difference if you use another operating system but the result should be the same). To confirm if your installation is right, type ‘python’ in your command line window. You should get:

Python 3.9.0 (tags/v3.9.0:9cf6752, Oct  5 2020, 15:34:40) [MSC v.1927 64 bit (AMD64)] on win32
Type "help", "copyright", "credits" or "license" for more information.

You can follow the python mongodb examples in this tutorial even if you are new to python.

We recommend that you set up a MongoDB Atlas free tier cluster for this tutorial.

Connecting Python and MongoDB Atlas

PyMongo has a set of packages for Python MongoDB interaction.

To install PyMongo, open command line and type:

python -m pip install pymongo

Tip: If you are getting “ModuleNotFoundError: No module named 'pymongo'” error, uninstall pymongo. Use pip uninstall pymongo command. Then, re-install using the installation command.

For this python mongodb tutorial, we use mongodb srv URI, so let’s install dnspython:

python -m pip install dnspython

Now, we can use pymongo as a python mongodb library in our code with an import statement.

Creating a MongoDB database in Python

The first step to connect python to Atlas is MongoDB cluster setup.

Next, create a file named in any folder to write pymongo code. You can use any simple text editor like Textpad/Notepad.

Create the mongodb client by adding the following:

def get_database():
    from pymongo import MongoClient
    import pymongo

    # Provide the mongodb atlas url to connect python to mongodb using pymongo
    CONNECTION_STRING = "mongodb+srv://<username>:<password>@<cluster-name>"

    # Create a connection using MongoClient. You can import MongoClient or use pymongo.MongoClient
    from pymongo import MongoClient
    client = MongoClient(CONNECTION_STRING)

    # Create the database for our example (we will use the same database throughout the tutorial
    return client['user_shopping_list']
# This is added so that many files can reuse the function get_database()
if __name__ == "__main__":    
    # Get the database
    dbname = get_database()

Use the connection_string to create the mongoclient and get the MongoDB database connection. Change the username, password and cluster name .

In this python mongodb tutorial, we will create a shopping list and add a few items. For this, we created a database ‘user_shopping_list’.

MongoDB doesn’t create a database until you have collections and documents in it. So, let’s create a collection next.

Creating a collection in Python

To create a collection, pass the collection name to the database. Make sure to have the right indentation while copying the code to your .py file.

collection_name = dbname["user_1_items"]

This creates a collection named user_1_items in the user_shopping_list database.

Inserting documents in Python

For inserting many documents at once, use the pymongo insert_many() method.

item_1 = {
"_id" : "U1IT00001",
"item_name" : "Blender",
"max_discount" : "10%",
"batch_number" : "RR450020FRG",
"price" : 340,
"category" : "kitchen appliance"

item_2 = {
"_id" : "U1IT00002",
"item_name" : "Egg",
"category" : "food",
"quantity" : 12,
"price" : 36,
"item_description" : "brown country eggs"

Let us insert a third document without specifying the _id field. This time we add a field of data type ‘date’. To add date using pymongo, use the python dateutil package. ISODate will not work with Python, as it is a Mongo shell function.

Install the package using the following command: python -m pip install python-dateutil

Add the following to

from dateutil import parser
expiry_date = '2021-07-13T00:00:00.000Z'
expiry = parser.parse(expiry_date)
item_3 = {
"item_name" : "Bread",
"quantity" : 2,
"ingredients" : "all-purpose flour",
"expiry_date" : expiry

We use the insert_one() method to insert a single document.

Open the command line and navigate to the folder where you have saved Execute the file using the python command.

Let’s connect to MongoDB Atlas UI and check what we have so far.

Login to your Atlas cluster and click on the collections button.

On the left side, you can see the database and collection name that we created. If you click on the collection name, you can view the data as well:

view of the database and collection name

view of data on click

The _id field is of ObjectId type by default. If we don’t specify the _id field, MongoDB generates the same. Not all fields present in one document are present in others. But MongoDB doesn’t stop you from entering data - this is the essence of a schemaless database.

If we insert item_3 again, mongodb will insert a new document, with a new _id value. But, the first two inserts will throw an error because of the _id field, the unique identifier.

Querying in Python

Let’s view all the documents together using find(). For that we will create a separate file

# Get the database using the method we defined in pymongo_test_insert file 
from pymongo_test_insert import get_database
dbname = get_database()

# Create a new collection
collection_name = dbname["user_1_items"]

item_details = collection_name.find()
for item in item_details:
    # This does not give a very readable output

Open the command line and navigate to the folder where you have saved Execute the file using the python command.

We get the list of dictionary object as the output:

dictionary list

We can view the data but the format is not all that great. So, let’s print the item names and their category:

print(item['item_name'], item['category'])

Although Mongodb gets the entire data, we get a python ‘KeyError’ on the third document.

Python KeyError

To handle missing data errors in python, use pandas.DataFrames. DataFrames are 2D data structures used for data processing tasks. Pymongo find() method returns dictionary objects which can be converted into a dataframe in a single line of code.

Install pandas library as:

python -m pip install pandas

Replace the for loop with the following code to handle KeyError in one step:

from pandas import DataFrame
# convert the dictionary objects to dataframe
items_df = DataFrame(item_details)

# see the magic

And don’t forget to comment the print(item['item_name'], item['category'])

The errors are replaced by NaN and NaT for the missing values.

NaN and NaT for the missing values.

Indexing in Python MongoDB

The number of documents and collections in a real-world database always keep increasing. It can take a very long time to search for specific documents -- for example, documents that have “all-purpose flour” among their ingredients -- in a very large collection. Indexes make database search faster, efficient, and reduce the cost of querying. For example, sort, count, match etc.

MongoDB defines indexes at the collection level.

For the index to make more sense, add more documents to our collection. Insert many documents at once using the insert_many() method. For sample documents, copy the code from github and execute python in your terminal.

Let’s say we want the items that belong to the category ‘food’:

item_details = collection_name.find({"category" : "food"})

To execute the above query, mongodb has to scan all the documents. To verify this, download Compass. Connect to your cluster using the connection string. Open the collection and go to the Explain Plan tab. In ‘filter’, give the above criteria and view the results:

Query results without index

Note that the query scans twelve documents to get three results.

Let us create a single index on the ‘category’ field.

category_index = collection_name.create_index("category")

Explain the same filter again on Compass UI:

Query results with index

This time only three documents are scanned because of the category index. We don’t see a significant difference in execution time because of fewer documents. But we see a huge reduction in the number of documents scanned for the query. Indexes help in performance optimization for aggregations as well. Aggregations are out of scope for this tutorial, but here’s an overview.


In this python mongodb tutorial, we learned the basics of pymongo and performed simple database operations. As a next step, explore using pymongo to perform CRUD operations with business data. If you did not work along with this tutorial, start now by installing MongoDB Atlas for free.

Ready to get started?

Launch a new cluster or migrate to MongoDB Atlas with zero downtime and connect to python today.


How do you connect MongoDB to Python?

There are 3 ways to connect MongoDB to Python:

  • PyMongo
    • The native driver for connecting mongodb and python. PyMongo has all the libraries to perform database operations from python code. Since pymongo is a low-level driver, it is fast and intuitive, and provides more control.
  • MongoEngine
    • MongoEngine is a Document Object Mapper. We can define a schema that maps application objects and document data.
  • Djongo
    • We use Djongo for python web applications using the Django framework. It converts existing SQL queries to mongodb query documents.

Learn more about using MongoEngine and Djongo.

Which database is best for Python?

Python works well with different databases. The choice depends on your project requirements. Opt for NoSQLdatabases like MongoDB if for example your application handles a flexible data schema.

Opt for relational databases like SQL if your application handles a rigid data schema.

For more information read NoSQL vs SQL Databases.

Is MongoDB good for Python?

Mongodb stores data in flexible and schema-less JSON-like documents. Python has rich libraries that directly process JSON and BSON data formats. Python integrates well with Mongodb through drivers like Pymongo, MongoEngine etc.

This makes Mongodb good for python by eliminating rigidity in the database schema.

How does Python store data in MongoDB?

Python stores data in MongoDB through libraries like PyMongo and MongoEngine. For web applications using the Django framework, we can use Djongo.

  • Pymongo - Pymongo is the native python driver for mongodb database. Since it is a low-level driver, it is faster and also a preferred way to connect python with mongodb.
  • MongoEngine - With mongoengine, we can create a schema (yes for a schema-less database). Mongoengine follows the ODM approach to map application classes and database documents.
  • Djongo - Djongo is a SQL transpiler. You can migrate existing SQL projects to mongodb without many changes to the code.

Learn more about using MongoEngine and Djongo.

How do you use MongoDB with Python?

We can connect MongoDB with Python using PyMongo. Pymongo is the native Python driver for MongoDB. It has a syntax similar to MongoShell, so that we can easily correlate and use the right method. For example, insertMany() on MongoShell corresponds to insert_many() in PyMongo. We can also connect python and mongodb using MongoEngine and Djongo. But, the preferred approach is to use PyMongo because it is a low-level driver that is faster and provides more control.

How do you get data from MongoDB using Python?

The most efficient and easy method to connect mongodb and python is to use pymongo. Pymongo is the native python driver for mongodb. To connect, we use the command pymongo.MongoClient() with the connection_string as argument. Then, we can use the find() method to get the required documents. Example:

import pymongo

# connect to mongodb from python using pymongo
client = pymongo.MongoClient(CONNECTION_STRING)
# open the database
dbname = client['user_shopping_list']
# get the collection
collection_name = dbname["item_details"]
# get the data from the collection
item_details = collection_name.find()

How do you insert data into MongoDB using Python?

To insert data, connect mongodb and python using pymongo. Pymongo is the native Python driver for mongodb. Once we connect, we can use pymongo’s methods like insert_one() and insert_many(). Example:

# Get the mongoclient
client = pymongo.MongoClient(CONNECTION_STRING)

# Get/Create database
dbname = client['user_shopping_list']

# Get/create collection
collection_name = dbname["item_details"]

# Create the document
item_1 = {"item_name": "Bread",...,"category" : "food",
"quantity" : 2}

# Insert one row

How do you create a database in MongoDB using Python?

We use PyMongo driver to create a mongodb database using python code. Example:

import pymongo

# Get the mongoclient
client = pymongo.MongoClient(CONNECTION_STRING)

# Get/Create database
dbname = client['user_shopping_list']