MongoDB is one of the most popular NoSQL databases for modern web applications, APIs, data-processing tools, and automation systems. Python, with its simple syntax and extensive ecosystem, is equally popular for backend development, data science, artificial intelligence, and scripting.

When these two technologies are combined, developers can build flexible and scalable applications without dealing with the rigid table-based structure of traditional relational databases.

In this guide, you’ll learn how to connect MongoDB with Python using the official MongoDB Python driver, how to perform CRUD operations, work with databases and collections, handle errors, and follow best practices for production applications.

What Is MongoDB?

MongoDB is a document-oriented NoSQL database that stores data in flexible, JSON-like documents.

Instead of storing information in rows and columns like MySQL or PostgreSQL, MongoDB stores documents inside collections.

A MongoDB document looks similar to a Python dictionary:

{
  "name": "John Doe",
  "email": "john@example.com",
  "age": 28,
  "skills": ["Python", "MongoDB", "FastAPI"]
}

This flexible structure makes MongoDB particularly useful for applications where data models can evolve over time.

Why Connect MongoDB With Python?

Python and MongoDB work well together because Python provides a simple development experience while MongoDB offers flexible document storage.

Some common use cases include:

REST APIs
Web applications
Automation scripts
Data collection systems
AI and machine learning applications
Content management systems
Analytics platforms
Real-time applications
Microservices

For example, a Python-based API can receive user information, validate it, and store it directly in MongoDB.

Python + MongoDB Architecture

A typical application looks like this:

┌──────────────────┐
│   Client / App   │
└────────┬─────────┘
         │
         │ HTTP Request
         ▼
┌──────────────────┐
│   Python API     │
│ Flask / FastAPI  │
│      Django      │
└────────┬─────────┘
         │
         │ PyMongo
         ▼
┌──────────────────┐
│     MongoDB      │
│                  │
│ Database         │
│   ├── Users      │
│   ├── Products   │
│   └── Orders     │
└──────────────────┘

The Python application communicates with MongoDB through a MongoDB driver.

What Is PyMongo?

PyMongo is the official Python driver for MongoDB.

It allows Python applications to:

Connect to MongoDB
Create databases and collections
Insert documents
Find documents
Update documents
Delete documents
Run queries
Create indexes
Execute aggregation pipelines

The driver translates Python operations into MongoDB database operations.

Prerequisites

Before learning how to connect MongoDB with Python, make sure you have:

Python 3 installed
MongoDB installed locally or a MongoDB Atlas account
Basic Python knowledge
A code editor such as VS Code

You can use either a local MongoDB server or MongoDB Atlas.

Step 1: Install PyMongo

The easiest way to install the MongoDB Python driver is with pip.

Open your terminal and run:

pip install pymongo

If your system uses python3 and pip3, you can use:

pip3 install pymongo

After installation, verify that PyMongo is available:

python -c "import pymongo; print(pymongo.version)"

If a version number is displayed, the installation was successful.

Step 2: Set Up MongoDB

You have two primary options for running MongoDB.

Option 1: Local MongoDB

If MongoDB is installed locally, the default connection URL is usually:

mongodb://localhost:27017/

The default MongoDB port is:

Make sure the MongoDB service is running before connecting from Python.

Option 2: MongoDB Atlas

MongoDB Atlas is MongoDB’s managed cloud database service.

Instead of running MongoDB on your own computer or server, Atlas hosts the database for you.

An Atlas connection string generally looks like:

mongodb+srv://<username>:<password>@cluster.mongodb.net/

You should never hard-code production credentials directly into your Python source code.

Instead, store sensitive values in environment variables.

Step 3: Connect MongoDB With Python

Now let’s create a simple Python script.

from pymongo import MongoClient

client = MongoClient("mongodb://localhost:27017/")

print("Connected to MongoDB")

This creates a MongoDB client and connects your Python application to the MongoDB server.

However, for real applications, it is better to verify the connection.

from pymongo import MongoClient

client = MongoClient("mongodb://localhost:27017/")

try:
    client.admin.command("ping")
    print("MongoDB connection successful!")
except Exception as error:
    print("MongoDB connection failed:", error)

The ping command checks whether MongoDB is reachable.

Step 4: Select a Database

Once you have a MongoDB client, you can select a database.

from pymongo import MongoClient

client = MongoClient("mongodb://localhost:27017/")

db = client["myapp"]

print("Database selected:", db.name)

MongoDB creates the database when you first store data in it.

You can also use:

db = client.myapp

Both approaches are valid.

Step 5: Create a Collection

MongoDB collections are similar to tables in relational databases.

For example:

users = db["users"]

You can now use the users collection to store user documents.

Unlike SQL databases, you generally don’t need to manually create a collection before inserting the first document.

Step 6: Insert a Document

Let’s insert a user into MongoDB.

user = {
    "name": "John Doe",
    "email": "john@example.com",
    "age": 28,
    "skills": ["Python", "MongoDB"]
}

result = users.insert_one(user)

print("Inserted ID:", result.inserted_id)

MongoDB automatically generates an _id field if you don’t provide one.

A stored document will look approximately like:

{
  "_id": "ObjectId(...)",
  "name": "John Doe",
  "email": "john@example.com",
  "age": 28,
  "skills": ["Python", "MongoDB"]
}

The generated _id uniquely identifies the document.

Inserting Multiple Documents

You can insert multiple documents using insert_many().

users_data = [
    {
        "name": "Alice",
        "email": "alice@example.com",
        "age": 25
    },
    {
        "name": "Bob",
        "email": "bob@example.com",
        "age": 32
    },
    {
        "name": "Sarah",
        "email": "sarah@example.com",
        "age": 29
    }
]

result = users.insert_many(users_data)

print("Inserted IDs:", result.inserted_ids)

This is useful when importing or processing multiple records.

Step 7: Read Data From MongoDB

MongoDB provides several ways to retrieve documents.

Find One Document

Use find_one() when you only need one document.

user = users.find_one({"email": "john@example.com"})

print(user)

You can also search using the document ID:

from bson import ObjectId

user = users.find_one({
    "_id": ObjectId("YOUR_OBJECT_ID")
})

Find Multiple Documents

Use find() to retrieve multiple documents.

for user in users.find():
    print(user)

You can also filter the results:

for user in users.find({"age": {"$gte": 25}}):
    print(user)

This query returns users whose age is greater than or equal to 25.

Step 8: Update Documents

MongoDB provides several update methods.

For example, to update a user’s age:

result = users.update_one(
    {"email": "john@example.com"},
    {"$set": {"age": 29}}
)

print("Modified documents:", result.modified_count)

The $set operator changes only the specified field.

This is important because you don’t have to replace the entire document.

Update Multiple Documents

You can update multiple documents with update_many().

result = users.update_many(
    {"age": {"$lt": 30}},
    {"$set": {"status": "young-adult"}}
)

print("Updated:", result.modified_count)

Step 9: Delete Documents

To delete one document:

result = users.delete_one({
    "email": "john@example.com"
})

print("Deleted:", result.deleted_count)

To delete multiple documents:

result = users.delete_many({
    "status": "inactive"
})

print("Deleted:", result.deleted_count)

Be careful with delete queries, especially in production environments.

MongoDB CRUD Operations With Python

CRUD stands for:

Create
Read
Update
Delete

Here’s a quick overview:

Operation	PyMongo Method	Example
Create	`insert_one()`	Add a user
Create Multiple	`insert_many()`	Add multiple users
Read One	`find_one()`	Get one user
Read Many	`find()`	Get users
Update One	`update_one()`	Update a user
Update Many	`update_many()`	Update multiple users
Delete One	`delete_one()`	Delete a user
Delete Many	`delete_many()`	Delete multiple users

Complete Python MongoDB Example

Here is a simple example that connects to MongoDB and performs basic CRUD operations.

from pymongo import MongoClient

client = MongoClient("mongodb://localhost:27017/")

try:
    client.admin.command("ping")
    print("Connected to MongoDB")

    db = client["company"]
    employees = db["employees"]

    # Create
    employee = {
        "name": "Alex",
        "role": "Backend Developer",
        "experience": 3
    }

    result = employees.insert_one(employee)
    print("Created:", result.inserted_id)

    # Read
    employee = employees.find_one({
        "_id": result.inserted_id
    })

    print("Employee:", employee)

    # Update
    employees.update_one(
        {"_id": result.inserted_id},
        {"$set": {"experience": 4}}
    )

    # Read updated document
    updated_employee = employees.find_one({
        "_id": result.inserted_id
    })

    print("Updated:", updated_employee)

    # Delete
    employees.delete_one({
        "_id": result.inserted_id
    })

    print("Employee deleted")

except Exception as error:
    print("Error:", error)

finally:
    client.close()

This example demonstrates the complete lifecycle of a MongoDB document.

Using MongoDB Atlas With Python

For cloud applications, MongoDB Atlas is a common choice.

Your connection string will typically look like:

mongodb+srv://username:password@cluster.mongodb.net/mydatabase

Instead of putting this directly into your code, use an environment variable.

Install python-dotenv

pip install python-dotenv

Create a .env file:

MONGODB_URI=mongodb+srv://username:password@cluster.mongodb.net/mydatabase

Then load it from Python:

import os

from dotenv import load_dotenv
from pymongo import MongoClient

load_dotenv()

mongodb_uri = os.getenv("MONGODB_URI")

client = MongoClient(mongodb_uri)

client.admin.command("ping")

print("Connected to MongoDB Atlas")

This keeps credentials separate from your application code.

A Better Project Structure

For larger Python applications, avoid creating the MongoDB connection everywhere.

A simple project structure could look like this:

python-mongodb-app/
│
├── app/
│   ├── __init__.py
│   ├── database.py
│   ├── models/
│   ├── routes/
│   └── services/
│
├── .env
├── .gitignore
├── requirements.txt
└── main.py

Your database connection can be centralized in database.py.

import os

from dotenv import load_dotenv
from pymongo import MongoClient

load_dotenv()

MONGODB_URI = os.getenv("MONGODB_URI")

client = MongoClient(MONGODB_URI)

db = client["myapp"]

Other parts of the application can then use the database connection instead of creating new clients repeatedly.

Connecting MongoDB With Python and FastAPI

MongoDB is frequently used with Python web frameworks such as FastAPI.

A simple FastAPI endpoint could look like this:

from fastapi import FastAPI
from pymongo import MongoClient

app = FastAPI()

client = MongoClient("mongodb://localhost:27017/")
db = client["myapp"]
users = db["users"]


@app.get("/users")
def get_users():
    return list(users.find({}, {"_id": 0}))

The endpoint retrieves users from MongoDB and returns them through the API.

For production applications, you should add proper validation, error handling, connection management, pagination, and response models.

MongoDB Query Examples With Python

MongoDB becomes particularly powerful when you combine PyMongo with query operators.

Find Users Older Than 30

users.find({
    "age": {"$gt": 30}
})

Find Users Between Two Ages

users.find({
    "age": {
        "$gte": 20,
        "$lte": 30
    }
})

Find Users With a Specific Role

users.find({
    "role": "developer"
})

Search by Multiple Conditions

users.find({
    "role": "developer",
    "experience": {"$gte": 3}
})

Sort Results

users.find().sort("age", 1)

Use 1 for ascending order and -1 for descending order.

users.find().sort("age", -1)

Using Indexes for Better Performance

Indexes can significantly improve MongoDB query performance.

Suppose your application frequently searches users by email:

users.create_index("email")

You can also create a unique index:

users.create_index(
    "email",
    unique=True
)

This prevents duplicate email addresses.

Important

Don’t create indexes for every field.

Indexes improve reads but consume storage and can increase the cost of write operations.

Create indexes based on actual query patterns.

MongoDB and Python: Common Mistakes

Understanding common mistakes can save significant debugging time.

1. Hard-Coding Database Credentials

Avoid:

client = MongoClient(
    "mongodb+srv://admin:password123@cluster.mongodb.net/"
)

Use environment variables instead.

2. Committing `.env` to Git

Your .env file may contain passwords, API keys, and database credentials.

Add it to .gitignore:

.env

Never commit secrets to a public repository.

3. Creating Too Many MongoClient Instances

Avoid creating a new client for every database operation.

Instead, create a reusable client and share the database connection across your application.

4. Forgetting to Close Connections

For scripts that finish execution, close the client:

client.close()

For long-running applications, use an appropriate application-level connection lifecycle.

5. Ignoring Errors

Database operations can fail because of:

Network problems
Invalid credentials
Duplicate keys
Connection timeouts
Invalid queries
Server availability issues

Use appropriate exception handling.

from pymongo.errors import PyMongoError

try:
    users.insert_one(user)
except PyMongoError as error:
    print("Database error:", error)

6. Returning MongoDB ObjectId Directly as JSON

MongoDB’s ObjectId is not a standard JSON type.

For example:

{
    "_id": ObjectId("...")
}

Many API frameworks require you to convert it before returning JSON.

A simple approach is to exclude _id when appropriate:

users.find({}, {"_id": 0})

For production APIs, use proper serialization rather than relying on ad-hoc conversions.

Best Practices for MongoDB With Python

Follow these practices when building production applications.

Use Environment Variables

Keep database URLs and credentials outside your source code.

Reuse Database Connections

Create a MongoDB client once and reuse it instead of opening a new connection for every query.

Validate Input

Never insert unvalidated user input directly into your database.

Create Appropriate Indexes

Index fields that are frequently queried, sorted, or used for uniqueness.

Use Projections

Don’t retrieve fields you don’t need.

users.find(
    {},
    {"name": 1, "email": 1, "_id": 0}
)

Implement Pagination

Avoid loading thousands or millions of documents at once.

users.find().skip(0).limit(20)

For very large datasets, cursor-based pagination is generally preferable to large offsets.

Handle Exceptions

Use PyMongo’s exception classes to distinguish database failures.

Keep Secrets Out of Git

Use .env, deployment secrets, or a dedicated secrets manager.

PyMongo vs MongoEngine

Python developers may encounter both PyMongo and MongoEngine.

Feature	PyMongo	MongoEngine
Type	MongoDB driver	ODM
Control	High	Higher-level abstraction
Learning Curve	Moderate	Easier for some models
Query Flexibility	Excellent	Good
Schema Modeling	Manual	Built-in
Performance Control	High	Abstracted
Best For	Direct MongoDB access	Model-driven applications

PyMongo is the official MongoDB driver and is a strong choice when you want direct control over MongoDB operations.

An ODM such as MongoEngine can be useful when you prefer working with Python models and schemas.

Real-World Example: User Registration System

Imagine you’re building a user registration API.

The client sends:

{
  "name": "Emma",
  "email": "emma@example.com",
  "password": "hashed-password"
}

Your Python backend validates the data and stores something like:

{
  "name": "Emma",
  "email": "emma@example.com",
  "password": "hashed-password",
  "created_at": "2026-08-21T10:30:00Z",
  "status": "active"
}

The flow becomes:

User
  │
  │ Registration Request
  ▼
Python API
  │
  ├── Validate Input
  │
  ├── Hash Password
  │
  └── Store Document
          │
          ▼
      MongoDB
          │
          ▼
    Registration Complete

In a real application, passwords should always be securely hashed using an appropriate password-hashing algorithm. Never store plain-text passwords.

When Should You Use MongoDB With Python?

MongoDB with Python is a good choice when your application needs:

Flexible document structures
Rapid application development
JSON-like data storage
Large-scale data handling
Frequent schema evolution
Python-based APIs
Data processing or automation
Integration with AI applications

However, MongoDB isn’t automatically the best database for every application.

If your application depends heavily on complex relational joins, strict relational constraints, or highly structured transactional data, a relational database may be a better fit.

Key Takeaways

Here are the most important things to remember about connecting MongoDB with Python:

PyMongo is the official MongoDB driver for Python.
Install it with pip install pymongo.
Use MongoClient to connect Python to MongoDB.
MongoDB databases contain collections, and collections contain documents.
Use insert_one() and insert_many() to create documents.
Use find_one() and find() to retrieve documents.
Use update_one() and update_many() to modify documents.
Use delete_one() and delete_many() to remove documents.
Store MongoDB credentials in environment variables.
Reuse MongoDB connections in long-running applications.
Use indexes and pagination to improve performance.
Validate input and handle database exceptions.

Frequently Asked Questions

1. How do I connect MongoDB with Python?

Install PyMongo using pip install pymongo, create a MongoClient, and provide your MongoDB connection string.

from pymongo import MongoClient

client = MongoClient("mongodb://localhost:27017/")
db = client["myapp"]

2. What Python library is used to connect to MongoDB?

PyMongo is the official Python driver for MongoDB. It provides APIs for connecting to MongoDB and performing CRUD operations, queries, indexing, and other database operations.

3. Can Python connect to MongoDB Atlas?

Yes. Python can connect to MongoDB Atlas using a MongoDB Atlas connection string with PyMongo.

client = MongoClient(MONGODB_URI)

For production applications, store the connection string securely in an environment variable.

4. Is MongoDB good with Python?

Yes. MongoDB and Python are widely used together for web APIs, automation, data processing, AI applications, and other software projects.

5. How do I insert data into MongoDB using Python?

Use the insert_one() method:

users.insert_one({
    "name": "John",
    "age": 30
})

For multiple documents, use insert_many().

6. How do I retrieve data from MongoDB using Python?

Use find_one() for a single document or find() for multiple documents.

user = users.find_one({"name": "John"})

For multiple documents:

for user in users.find():
    print(user)

7. Is PyMongo better than MongoEngine?

They serve different purposes. PyMongo provides direct access to MongoDB and more control, while MongoEngine provides an ODM abstraction with model-based development.

For developers who want direct MongoDB access, PyMongo is usually the natural starting point.

8. How can I secure a MongoDB connection in Python?

Use environment variables for connection strings, enable authentication, use secure connections for remote databases, restrict network access, avoid committing credentials to Git, and follow the security recommendations of your MongoDB deployment.

How to Connect MongoDB With Python: A Complete Beginner’s Guide