BLOGAnnounced at MongoDB.local NYC 2024: A recap of all announcements and updates — Learn more >

How to Use Django with MongoDB

Not a MongoDB user yet?

Python, the top programming language for data science, has always been a great match with MongoDB for building powerful applications. Django, the most popular Python web framework, is an ideal tool to build secure and easy-to-maintain applications using MongoDB.

Using MongoDB with Django is advantageous because:

  • Every second, more and more unstructured data is generated from various sources like chats, real-time streams, feeds, and surveys.
  • Data needs to be stored securely into a storage system that is scalable, performant, and not rigid, making it easy to perform data analysis and visualizations.
  • Data retrieval is easy because of the simpler structure of storage. That simplicity makes it easy to access even nested items and doesn't require complex joins.

MongoDB with Django satisfies the above criteria and provides much more. That is what we will learn in this tutorial.

About MongoDB

MongoDB is a flexible, schema-less, JSON-style, document-based database. Here's a side-by-side comparison showing the insertion of a medicine into a pharmacy database in SQL and MongoDB:

SQL    MongoDB   
example of SQL create table / insert into statements to add medicine to a pharmacy database    example of MongoDB insert one statement to add medicine to a pharmacy database    

Note that we inserted a record while creating the collection. In MongoDB, if the collection doesn’t exist, it is created on the fly.

In SQL, if we forget to provide a medicine_id, the record will fail as it is the primary key (not null). Whereas the default primary key in MongoDB is the _id field, we can insert the record without the medicine_id.

High availability, indexing, and non-reliance on complex joins are some other benefits of using MongoDB. Atlas provides security, scalability, and zero downtime patches and upgrades. Atlas is perfect to store big volumes of structured and unstructured data.

MongoDB Atlas

If you are going to work with big data, you will need to use a cloud-based service. This is where MongoDB Atlas's ability to support limitless clusters can help. You can easily deploy, operate, and scale MongoDB with Atlas. Learn more about MongoDB Atlas.

Get started with Atlas by following the MongoDB Atlas tutorial instructions.

How Does Django Connect to MongoDB?

There are three ways to connect Django to MongoDB:

  1. PyMongo: PyMongo is the standard driver through which MongoDB can interact with Django. It is the official and preferred way of using MongoDB with Python. PyMongo provides functionality to perform all the database actions like search, delete, update, and insert. Since PyMongo is available with PyPI, you can quickly install it using a pip command.
  2. MongoEngine: MongoEngine is a Python Object-Document-Mapper. It’s similar to Object-Relational-Mapper in relational databases. MongoEngine has a declarative API that is easy to learn and use.
  3. Djongo: If you are using a relational database like SQL and want to migrate to MongoDB, for that you can use Djongo. Without changing the Django ORM, Djongo transpiles all the SQL queries to MongoDB syntax queries.

Which approach to connect to Django MongoDB is better? Let us explore this in the following sections.

Django and MongoDB Setup

To get the integration working, you should have a Django and MongoDB setup. If you have Python on your machine, you can install Django using pip. If you wish to install Django in a specific environment instead of the whole system, you can create a virtual environment. Use pip/pip3 depending on your Python version:



pip install virtualenvwrapper-win

Mac OS / Linux:

pip install virtualenvwrapper



mkvirtualenv MyProjectEnvt

Mac OS / Linux:

virtualenv MyProjectEnvt


Mac OS / Linux

source MyProjectEnvt/bin/activate


workon MyProjectEnvt

To deactivate the virtual environment, you can just type the command deactivate.

Now install Django using pip install Django.

To start a Django project, go to the folder where you want to start the project and use the below command:

django-admin startproject <project_name>.

For example,

C:\Users\myuser\project_files>django-admin startproject MyFirstDjangoProj
C:\Users\myuser\project_files>cd MyFirstDjangoProj

To create an app, use the following command:

python startapp myfirstapp

If you are using the Python version >= 3.0, replace python with python3 in your commands.

Inside the app, we can have many models that will be mapped to the collections and documents in MongoDB.

Once you start the project, all the files will be available in the project folder. Start the server using the python runserver command.

Your Django setup is now complete.

If you don’t already have MongoDB set up, use MongoDB Atlas to make the most of cloud hosting. Atlas works seamlessly with all the major cloud providers.

Connect Django and MongoDB Using PyMongo

PyMongo is very efficient for writing JSON data to MongoDB and allows the use of MongoDB queries in the Python code itself. We can retrieve data in a dictionary like syntax using PyMongo.

Install PyMongo easily using the pip/pip3 command:

pip install pymongo[snappy,gssapi,srv,tls]

If you are using a virtual environment (which you are!), you have to install pymongo in ..\venv\Lib\site-packages folder.

Also, install dnspython for using mongodb+srv:// URIs with the command:

pip install dnspython

Using PyMongo, we can concurrently run multiple databases by specifying the right database name to the connection instance.

Let us create a sample pymongo session. There are two approaches for this:

  1. We can create a client in the utils file that can be used by any view that wants to interact with MongoDB. Create a file in your project folder (same location as and instantiate the client:

    from pymongo import MongoClient
    def get_db_handle(db_name, host, port, username, password):
     client = MongoClient(host=host,
     db_handle = client['db_name']
     return db_handle, client

This method can then be used in ./myfirstapp/

  1. Another approach to get the connection is to use the connection_string:

    from pymongo import MongoClient
    client = MongoClient('connection_string')
    db = client['db_name']


    connection_string = mongodb+srv://<username>:<password>@<atlas cluster>

    For example,

    makemyrx_db = client['sample_medicines']
    #collection object
    medicines_collection = makemyrx_db['medicinedetails']

You may have seen the Connection class used in other code samples or tutorials. Connection has been deprecated, so don’t use it.

If you are on a default port and host, simply call MongoClient(). To connect to localhost, we can specify host and port explicitly as:

MongoClient(‘localhost’, 27017)


use the URL format MongoClient(‘mongodb://localhost: 27017/’)

Since we have created the client here, we need to comment the DATABASES section in the file. Comment the same using triple quotes.

Connect Django and MongoDB Using MongoEngine

MongoEngine is an ORM layer on top of PyMongo. So, you still need PyMongo (>=3.4) on your system to use MongoEngine.

Using MongoEngine to connect Django and MongoDB gives you fields like ListField and DictField to handle huge unstructured JSON data.

First, install MongoEngine using:

pip install mongoengine

As we have seen in the previous section, while using PyMongo, we have to comment the DATABASES section in Then, to use MongoEngine, add the following:

import mongoengine
mongoengine.connect(db=db_name, host=hostname, username=username, password=pwd)

With MongoEngine, we have to define a schema in the file of the Django application. MongoDB is schemaless. The schema is enforced only until application level, making any future changes fast and easy.

MongoEngine is similar to Django’s default ORM, but with the following changes in

Django’s ORMMongoEngine
from django.db import models

from mongoengine import Document, fields or from mongoengine import *

Model Document
models.CharField fields.StringField()

The difference is that we were using models, which are replaced by documents and fields when MongoEngine is used.

There are many other tools written to work with PyMongo.

Connect Django and MongoDB Using Djongo

Djongo is an improvement over PyMongo in that developers need not write lengthy queries. It maps Python objects to MongoDB documents, i.e., Object Document Mapping (ODM). Djongo ensures that only clean data enters the database. By performing integrity checks, applying validations, etc. with Djongo, there is no need to modify the existing Django ORM.

Install Djongo:

pip install djongo

Now, go to your project folder (example, MyFirstDjangoProj), and open file. You can edit it on Textpad, Python IDE, or any editor. Search for DATABASES, and change the settings to point to MongoDB. The ENGINE will be djongo and the database name (NAME) will be your MongoDB database name.

       'default': {
           'ENGINE': 'djongo',
           'NAME': 'db-name',

If your database is not on localhost or is secured, you should also fill in the CLIENT information like HOST, USERNAME, PASSWORD, etc.

        'default': {
            'ENGINE': 'djongo',
            'NAME': 'your-db-name',
            'ENFORCE_SCHEMA': False,
            'CLIENT': {
                'host': 'mongodb+srv://<username>:<password>@<atlas cluster>/<myFirstDatabase>?retryWrites=true&w=majority'

Make sure that the app-name is added in the INSTALLED_APPS setting of your


Now that we have the Django project (and app), you can create the collections in MongoDB using the commands:

python makemigrations <app-name>
python migrate

The collections (Django model in the app—note that we are talking about the app and not the project) will be created. You can check the same by opening Django Admin.

You can use the Admin GUI or insert data into collections manually.

To use the admin console, open your browser and go to (or localhost). You should create a superuser to enter the admin console. If you do not have any models in your app, follow the Django tutorial on how to create and register models.

If you want Djongo to go migration-free, set ENFORCE_SCHEMA: False in your database configuration. With this setting, the collections are created on the fly and Djongo won’t transpile SQL statements into MongoDB commands.

Django and MongoDB Tutorial

(Feel free to code along or to download the full code from this GitHub repo.)

In this quick tutorial, we will demonstrate how to use PyMongo to do simple CRUD operations. For this, let’s create a PyMongo session:

import pymongo
#connect_string = 'mongodb+srv://<username>:<password>@<atlas cluster>/<myFirstDatabase>?retryWrites=true&w=majority' 

from django.conf import settings
my_client = pymongo.MongoClient(connect_string)

# First define the database name
dbname = my_client['sample_medicines']

# Now get/create collection name (remember that you will see the database in your mongodb cluster only after you create a collection
collection_name = dbname["medicinedetails"]

#let's create two documents
medicine_1 = {
    "medicine_id": "RR000123456",
    "common_name" : "Paracetamol",
    "scientific_name" : "",
    "available" : "Y",
    "category": "fever"
medicine_2 = {
    "medicine_id": "RR000342522",
    "common_name" : "Metformin",
    "scientific_name" : "",
    "available" : "Y",
    "category" : "type 2 diabetes"
# Insert the documents
# Check the count
count = collection_name.count()

# Read the documents
med_details = collection_name.find({})
# Print on the terminal
for r in med_details:
# Update one document
update_data = collection_name.update_one({'medicine_id':'RR000123456'}, {'$set':{'common_name':'Paracetamol 500'}})

# Delete one document
delete_data = collection_name.delete_one({'medicine_id':'RR000123456'})

Next, you can connect to your MongoDB Atlas cluster and verify the same. Click on the collections and you can spot the newly created database and the collection on the left: database view

On the right side, you will see one record (as we have deleted one): query results

Next Steps

Now that we know the different ways to connect Django and MongoDB, we have to choose the right one for our project. The approaches have their own pros and cons.

For example, if you are starting from scratch, MongoEngine is a good way to go, as it can easily deal with a lot of unstructured data. If you have a lot of complex queries to write in your application, you should go with PyMongo.

Djongo is more suitable if you have a Django project that needs to migrate to MongoDB from another database, as that would require the least amount of code changes.

Ready to get started?

If you are going to work with big data, you will need to use a cloud-based service. This is where MongoDB Atlas's ability to support limitless clusters can help.


Can I use MongoDB with Django?

Yes, there are three ways to use MongoDB with Django.

  • PyMongo is the official way to connect MongoDB with Django and is supported by MongoDB. It is the native Python driver for MongoDB. It supports MongoDB versions 2.6, 3.x, 4.0, and 4.2.
  • MongoEngine is a Document-Object Mapper similar to an ORM in relational databases. It uses a declarative API to build Django projects using MongoDB. It is a library that provides abstraction over and above PyMongo.
  • Djongo is an SQL to MongoDB transpiler for Django projects and is an extension to the traditional Django ORM framework. Djongo maps Python objects to MongoDB documents.

What is Django and MongoDB?

Django is an extremely popular Python web application framework. MongoDB provides a highly scalable, flexible way to store and retrieve huge volumes of unstructured data. Combining Django and MongoDB offers the benefits of both along with high application performance.

How does Django connect to MongoDB?

There are three ways to connect Django with MongoDB. They are PyMongo, MongoEngine, and Djongo.

PyMongo is the officially supported way to connect Django and MongoDB. Using MongoEngine provides additional support for Python list and dict objects in Django model objects. If your project uses a relational database and you want to migrate to a non-relational database, like MongoDB, Djongo is a good option that transpiles SQL query string to MongoDB query documents.

Which database is best for Django?

Django is a web framework for Python, which is best known for its applications in data science. Although relational databases are quite popular because of their usage. Developers are starting to shift towards NoSQL databases due to the scalability, availability, and flexibility they offer. MongoDB, one of the most popular NoSQL databases, stores unstructured data in the form of collections and documents that are easy to retrieve. MongoDB also provides Charts, through which you can perform simple aggregations and view visualizations helpful for data analysis.