How To Delete MongoDB Documents Using Python


Delete MongoDB documents PyMongo is an important part of your regular maintenance routine for your MongoDB collections. As you add, modify, and analyze stored data, it becomes even more essential to clean out the clutter and remove MongoDB documents Python. The more organized your collections are, the easier it may become for you to make room for more relevant documents based on your needs.

If you’re just starting out and learning about how to delete MongoDB documents Python, this tutorial will explain the basics. Advanced users, if you already know how it’s done and want to skip the details of this lesson, you can go straight to Just the Code.


  • MongoDB – Download MongoDB and install it. Check the version with the mongo --version command like this below:
mongo --version
  • PyMongo Driver – Download the Python driver. Use the pip3 package manager to install PyMongo, the Python 3 MongoDB driver like this below:
pip3 install pymongo
  • It’s a good idea to install BSON library for MongoDB. Using the ObjectID class from the library might come in handy when you want to delete a document by it’s _id.
pip3 install bson
  • Create a sample MongoDB collection with a few unimportant test documents you can delete documents PyMongo as you practice with this tutorial.

Get your sample MongoDB collection ready for querying documents

  • Import MongoClient from PyMongo

  • Make a MongoClient instance

  • From the MongoClient instance you just made, construct objects of a database and at least one collection. You’ll use those for this lesson because you’ll need to delete documents after you make the appropriate API calls.

# From the PyMongo library, do importation of the MongoClient class
from pymongo import MongoClient

# Make a MongoClient fresh instance
mongo_client = MongoClient('mongodb://localhost:27017')
  • Get the database and a collection from it from the instance of the MongoDB client.
# get access to a MongoDB database and one of its collections
db = mongo_client.some_database
col = db.some_collection

NOTE: You won’t see a collection of documents if some_collection isn’t there. It will slowly be created after you add documents though, however, you won’t get a warning or see an exception raised by PyMongo. For that reason, make sure your collection does exist.

Locate some MongoDB documents for deletion

  • Verify that you made a PyMongo instance of a collection and that it contains documents. To do this, find a list of databases in MongoDB with the method list_database_names().
database_list = mongo_client.list_database_names()

Make an API call with the method database_names()

  • To the database_names() method, pass a database name’s string that you’ve chosen from the list. You should see a collection list of MongoDB documents for that database.
col_list = db.list_collection_names()
  • Next, use the method count_documents() to pass a dictionary object ({}). It must be empty. The collection’s documents will be represented by an integer.
# make a collection object
col = db["Some Collection"]

# get the number of documents in the collection
print ( "TOTAL DOCS:", col.count_documents({}) )
  • Another way to determine the number of documents of a collection is to use its find() method. The Cursor object will contain the documents. To get the results quickly, use the function enumerate() function, or the function for.
# get a list of a collection's documents
col_docs = col.find()

# iterate the list of document's returned by find()
for doc in col_docs:
    print (doc)

NOTE: Keep in mind, the old count() Cursor object method is out of date. If you try it now, you’ll raise an exception. To get the complete number of documents, remember to use the Collection.count_documents() method instead.

Screenshot of PyMongo returning a Cursor object of MongoDB docs and an integer from the count_documents() method

  • All documents content and IDs are listed in the Cursor object. Make API calls with a Python dictionary object. State your query using a document’s ID or content. Then you can delete that document.

Make a delete-query filter for a Python dictionary

  • Query the Python dictionary and pass it to either method delete_many() or delete_one() based on how many documents as well as which ones you want to delete.
# document(s) matching this query will get deleted
some_query = {"target field" : "target value"}
  • Be sure to check the target field. It is the dictionary key for the document.

  • Verify that the target value matches the document’s value as well.

Use the find_one_and_delete() method to return deleted documents’ JSON contents

  • Pass a query to the find_one_and_delete() method to return deleted documents.

NOTE: To return results, it’s necessary to pass the ({}) dictionary object, empty ones too.

result = collection_object.find_one_and_delete( {} )
  • You can tell the deleted document when you call the result object’s "_id" key attribute or value() method.
# print the dict values returned by method call
print ("find_one_and_delete:", result.value())

# print the _id key ONLY if the result is not None
if ("_id" in result):
    print ("find_one_and_delete ID:", result["_id"])
  • A NoneType object will be returned in matchless or empty collections.

The correct MongoDB API calls to use to delete documents in a collection

  • Only use find_one_and_delete(), delete_many(), or delete_one(); otherwise, you’ll get warning message.

The Remove() method is out of date, so use delete_one() or delete_many() to delete documents

Screenshot of PyMongo warning that remove() and database_names() are deprecated

Make an API call using the delete_one() method to delete a single document

  • Although you can have many matches, sometimes you might want to just delete one document. In that case, use the method delete_one().
result = some_collection.delete_one(some_query)

# print the API call's results
print("API call recieved:", result.acknowledged)
print("Documents deleted:", result.deleted_count)
  • You’ll see the deleted documents–one or more–when the pymongo.results.DeleteResult is returned.

  • A 1 value next to the result.deleted_count means that one document matched the query; a 0 value indicates no matches. if any documents

The way to remove an unspecified MongoDB document

Remove a document where the JSON document body isn’t a criterion for removing the document.

  • Use the method call delete_one() and pass the Python empty ({}) dictionary to it.
result = collection_object.delete_one({})

# print the API call's results
print("API call recieved:", result.acknowledged)
print("Documents deleted:", result.deleted_count)
  • If the results return at a minimum one document, you should see a 1 represented for the result.deleted_count.

Find the ObjectID of a document to delete it

  • The 12-byte, encoded bson.objectid.ObjectId BSON object comes with every document. It’s a timestamp index ID that is unique to each file.

Use MongoDB query methods to query the "_id" of a document you want to delete

  • The API query methods in MongoDB let you pass BSON objects. Take method delete_one(), for example. When queried using that method, you can delete a document that matches the query _id.

How to bypass a PyMongo NameError: <span>name 'ObjectId' is not defined exception

  • The ObjectId class for the BSON library is what you’ll need to import to avoid raising any type of NameError exception. Go ahead and import the BSON library’s class ObjectId now.
from bson import ObjectId

NOTE: Install the BSON library with the pip3 package manager if you get an ImportError.

Query the ObjectId value of the _id field when calling the method delete_one() to complete a MongoDB document deletion

Pass these two things to the delete_one() method:

  • The dictionary key is the "_id"

  • The value is the BSON ObjectId that’s encoded

col = mongo_client["Some-Database"]["Some Collection"]
result = col.delete_one(
        "_id" : ObjectId("5cf8c6838dbf4d4c309c3f39")

NOTE: Always pass the BSON ObjectId to the call method. A DeleteResult object will be returned if you try to pass only the _id string in place of the BSON ObjectId. > >Moreover, you’ll get an object NoneType object if you try to pass only _id string in place of the BSON ObjectId when you use the find_one() or find() method.

Screenshot of find_one() and delete_one() method calls querying _id BSON ObjectIds

How to use the delete_many() method

  • Pass a Python dictionary that is empty to the delete_many() method of the collection object to delete all of the documents in a MongoDB collection.
result = some_collection.delete_many({})

# print the results of the API call
print("API call recieved:", result.acknowledged)
print("Documents deleted:", result.deleted_count)

How to use range queries to delete several documents

Conduct a number or date range deletion by using either:

  • (gt) greater than

  • (lt) less than

Delete one or more documents with a range date that is clear-cut use of these methods:

  • delete()

  • delete_many()

col = db["Some Collection"]

# delete all docs before ($lt) a specific date
result = col.delete_many({"date": {"$lt": "2015-02-05"}})
print ("delete count:", result.deleted_count)
  • Confirm the deleted documents were actually removed by viewing the object results.DeleteResult.

NOTE: The API call method Remove() will soon be outdated, so if you try to use it, you’ll raise an exception.


Deleting documents in MongoDB is an ongoing task that keeps your collections clean and uncluttered. As you learned from this tutorial, there are several good ways to delete MongoDB documents Python. These include find_one_and_delete(), delete_one(), and delete_many() methods. One option that will soon be unavailable forever to delete MongoDB documents is the Remove() method. Practice the methods outlined in this tutorial to confidently delete documents PyMongo and raise fewer exceptions.

Just the Code

Here’s a complete code example to remove MongoDB documents Python to use as a guide.

# import the MongoClient class from pymongo library
from pymongo import MongoClient

# create a new client instance of MongoClient
mongo_client = MongoClient('mongodb://localhost:27017')

# find a MongoDB db and col with docs to delete
database_list = mongo_client.list_database_names()
print ("list_database_names:", database_list)

col_list = db.list_collection_names()
print ("list_collection_names:", col_list)

# get access to a MongoDB database and one of its collections
db = mongo_client.some_database
col = db.some_collection

# find out if it has documents
print (, "document total:", col.count_documents({}))

# document matching this query will get deleted
some_query = {"target field" : "target value"}
result = collection_object.find_one_and_delete( some_query )
print("docs deleted:", result.deleted_count)

# delete just one doc
result = collection_object.delete_one( some_query )
print ("result:", type(result), "-- deleted count:", result.deleted_count)

# delete just one AND have the API call return its contents
deleted_doc = collection_object.find_one_and_delete( some_query )
print ("deleted:", deleted_doc)

# delete many docs using a query
query = {"field" : "value"}
result = some_collection.delete_many( query )
print("docs deleted:", result.deleted_count)

# delete ALL documents on a MongoDB collection
result = some_collection.delete_many({})

# print the results of the call
print("API call recieved:", result.acknowledged)
print("docs deleted:", result.deleted_count)

Pilot the ObjectRocket Platform Free!

Try Fully-Managed CockroachDB, Elasticsearch, MongoDB, PostgreSQL (Beta) or Redis.

Get Started

Keep in the know!

Subscribe to our emails and we’ll let you know what’s going on at ObjectRocket. We hate spam and make it easy to unsubscribe.