Summary
This guide explains how to connect Django to MongoDB using the official Django MongoDB Backend. You’ll learn how to install and configure the integration, create a project and app, deploy to MongoDB Atlas, and perform CRUD operations—all with links to the official MongoDB documentation so you can follow code examples there.
Table of Contents
- Why use Django with MongoDB?
- MongoDB (NoSQL) vs. SQL databases
- How Django connects to MongoDB and why it matters
- Set up your environment for Django MongoDB
- How to connect Django to MongoDB Atlas for cloud deployment
- Django MongoDB Backend tutorial
- Conclusion: Next steps
- Frequently asked questions
- Recommended reading
Why use Django with MongoDB?
Developers have been using MongoDB with Django through third-party packages for years despite the lack of official support. That changed in 2025, when MongoDB released the first official Django integration—Django MongoDB Backend. It connects Django’s Python-based web framework with MongoDB's flexible document model via an integration built on PyMongo, the official MongoDB driver for Python.
As applications started processing more data from sources like IoT sensors, real-time activity feeds, images, and videos, traditional relational databases like PostgreSQL and MySQL struggled to keep pace.
Developers often had to build complex workarounds to handle the structured, semi-structured, and unstructured data that modern applications required. That extra effort took time and slowed development. That’s when many teams turned to more flexible NoSQL databases, such as MongoDB.
MongoDB gives developers a secure, flexible data format that scales easily and handles large, evolving datasets without the need for complicated joins. It’s designed to store data of any type—structured, semi-structured, or unstructured. And it's highly available, great for analytics, and makes visualization simple. If you’re working with big data, MongoDB’s fully managed cloud service, MongoDB Atlas, lets you deploy, operate, and scale easily with no-downtime patches and upgrades.
When connected, developers can:
- Work with structured and unstructured data without adhering to a rigid schema.
- Easily increase storage and resources as the application grows.
- Keep things running smoothly with quick reads and writes (no complex joins required).
- Add new fields or structures without having to rework the entire database.
- Analyze data faster with built-in aggregation tools that group, filter, and analyze JSON documents directly.
These capabilities let teams ship features faster with less boilerplate code and fewer workarounds.
Learn how Amazon transitioned from relational to NoSQL databases.
MongoDB (NoSQL) vs. SQL-based databases
MongoDB is a non-relational, schema-less database that stores information as JSON-style documents. In contrast, traditional relational databases such as Postgres and MySQL rely on predefined schemas, tables, and joins, whose rigid structure can make development slower when dealing with large or rapidly changing datasets—precisely the kind you’ll find in modern web applications.
Many developers start with SQL databases like SQLite or MySQL because they’re easy to set up and work well for smaller, structured datasets. However, as applications scale and data types diversify, that same rigidity can become a hindrance. They also rely on a single SQL query string to define how information is retrieved or updated, which can be rigid when dealing with dynamic or unstructured data.
Key differences
- Automatic collection creation: MongoDB automatically creates new collections as you insert new information—no setup needed. With SQL databases, you usually have to define tables and columns in advance before you can start adding data.
- Simple inserts: In SQL, inserts can fail if a required primary key is missing. MongoDB handles this automatically by assigning each document an “_id” field, ensuring records are saved even without predefined keys.
- Performance and scalability: MongoDB is built for flexibility and scalability. It provides high availability, indexing, and strong performance without the need for complex joins or rigid schema.
Learn more about the differences between NoSQL vs SQL.
How Django connects to MongoDB and why it matters
A Django project is the main framework that holds your web application’s settings, database configurations, and apps. Each project can include one or more apps—self-contained modules that handle specific features like user authentication or blog posts.
While developers have historically used third-party libraries like MongoEngine or Djongo, this guide focuses on the official backend.
Built and maintained by MongoDB engineers, this backend provides full Django object-relational mapping (ORM) compatibility and is built on PyMongo, the official Python driver.
The official backend eliminates the need for complex workarounds by translating Django ORM queries—such as create, read, update, and delete operations—into equivalent MongoDB operations that interact directly with JSON-style documents. The backend serves as your project’s default database engine, supporting both local deployments and MongoDB Atlas clusters for seamless scalability.
How the official backend and PyMongo work together
To connect Django with MongoDB, your project uses two key components that work as a team:
- PyMongo: This is MongoDB’s official Python driver. It’s the low-level tool that handles the direct communication and sends your application's commands to the database.
- Django MongoDB Backend: This is the Django integration package. It acts as a "translator," converting Django ORM commands (like Model.objects.create() or Model.objects.filter()) into operations that PyMongo can understand and execute.
You don't need to install PyMongo separately. When you follow the setup steps to install the django-mongodb-backend package, it will automatically install PyMongo and all other required dependencies for you, reducing setup code and potential errors.
Your next step is to set up your environment and install that single backend package.
Set up your environment for Django and MongoDB
The backend setup is straightforward, but ensuring version alignment is critical, so take a moment to verify your environment before installation.
Step 1: Verify versions match
Before you begin, make sure:
- You have the latest supported version of Python installed.
- You installed Django in a virtual environment.
- The official backend is the same version number as your Django installation.
For example, if you're using Django 5.2, install Django MongoDB Backend 5.2.
You can check the full compatibility matrix in the official Driver Compatibility Tables documentation.
Why version matching matters: Using mismatched versions will cause installation or runtime errors, so it’s worth double-checking before you start. It can also cause failed integrity checks during migration or deployment.
After confirming version alignment, it’s time to install the backend.
Step 2: Install the backend
The backend automatically links your Django models to MongoDB, letting your app store and retrieve data directly. It also installs dependencies like PyMongo, allowing it to use MongoDB as its default database engine, so you don’t need to install PyMongo separately.
For step-by-step instructions, read more about how to install the backend documentation.
Once your local connection is working, you can create your Django project.
Step 3: Create a connection string
You can connect to your MongoDB deployment using a connection string (also called a connection URI). It tells the driver where your database is and how to connect to it securely.
For step-by-step instructions, see the connection string documentation.
Step 4: Configure the database connection
Next, open your project’s settings.py file and update the DATABASES setting with your connection string and database name. This step tells Django where to find your MongoDB instance—whether it’s running locally or hosted on MongoDB Atlas.
Be sure the ENGINE key specifies "django_mongodb_backend" as your database engine. Once connected, MongoDB becomes your project’s default database for storing and retrieving data.
Your models can read and write to collections just like they would for any other database. After updating your project's settings, check the console output to confirm you've successfully connected to your MongoDB instance.
For detailed steps, see the configuration guide.
How to connect Django to MongoDB Atlas for cloud deployment
Once you configure your local connection, you can take it a step further with MongoDB Atlas, MongoDB’s fully managed cloud service that handles scaling, performance, and security for you. Atlas automatically manages your clusters, configurations, and upgrades, allowing you to focus on development instead of infrastructure.
You can deploy a MongoDB Atlas cluster in just a few clicks and easily connect Django to Atlas in your production environment using your Atlas connection string.
Steps to get started:
- Sign up for MongoDB Atlas—it’s free to begin.
- Follow the Atlas tutorial to deploy your first cluster and select MongoDB as your preferred database service.
- Choose your preferred cloud region and configuration in the deployment interface.
- Connect Django to your MongoDB cluster using the connection string provided in Atlas.
Once your local and cloud environments are configured, you’re done with the setup and ready to build your first application with MongoDB with the tutorial.
Django and MongoDB Backend tutorial: Step-by-step guide
The video below offers a high-level walkthrough of the integration process. For the detailed, step-by-step instructions, keep reading.
This tutorial walks you through the process of integrating Django with a MongoDB database for modern web applications. You’ll see how it interacts with local and cloud environments through MongoDB Atlas, which supports automatic scaling and global deployments.
In this tutorial, you’ll structure a project, connect the database, and run CRUD without raw database code.
Step 1: Create a tutorial Django project
Start by using the Django project template, which provides a standard folder structure, creating your complete project folder with settings, management scripts, and app configuration files ready for use.
Step 2: Create the sample Django application
Each project can include multiple Django applications—self-contained modules that handle specific features or functions, such as user authentication, blog posts, or dashboards. Your project is like an entire website, and each app is a piece of it.
To jump-start your work, you can use the app template on GitHub. This template offers pre-built settings, directories, and sample files that help you start developing quickly and avoid common setup errors.
For a complete working example that uses the same database and schema, explore MongoDB’s sample mflix application on GitHub.
How the app works
The app template follows Django’s standard structure:
- Models: Represent MongoDB collections and define document structures.
- Views: Handle data logic and presentation using built-in features.
- Templates: Control how data appears on web pages using the render() method.
- URLs: Map routes between views and templates.
It also includes:
- Contrib modules (such as contrib import admin or django.contrib.admin), letting you manage your MongoDB collections through the Django Admin.
- Authentication and session management for secure user handling.
Step 3: Define your application structure
Define your models, views, templates, and URLs using standard ORM conventions. These components let you use familiar features, such as forms, authentication, and contrib.admin—with MongoDB as your NoSQL database.
This setup enables full object-document mapping (ODM) between Django and MongoDB, also known as a Python object document mapper or document object mapper.
Learn more in the backend guide.
Step 4: Apply migrations
Run migrations (for example, "python manage.py migrate") to keep your models in sync with collections. Whenever you modify your models, Django migrations automatically update your MongoDB collections.
You can confirm successful migrations by checking the output from Django’s migration tool.
Learn more about how migrations work.
Step 5: Run CRUD operations
With your models and collections ready, you can perform the four standard CRUD operations—create, read, update, and delete—by using the Python interactive shell. You can also add or modify collections manually in the Django Admin view.
Examples:
- Create: Add a new record, like a movie or viewer.
- Read: Display data through views and templates.
- Update: Modify existing records directly through Django.
- Delete: Remove information you no longer need.
These examples show how the Django ORM seamlessly integrates with your MongoDB database.
Once your models and collections are ready, start your Django server and test your app.
Explore CRUD examples in the Interact with Data guide.
Conclusion: Next steps
You're ready to start building. Visit the official backend documentation to dive deeper, explore the source code on GitHub, and join the community by reporting issues or requesting features in the INTPYTHON JIRA project.