Connect PyMongo to MongoDB

You've built your models, your API is ready, and now you're staring at a wall between Python and your data: how do you actually connect PyMongo to a running MongoDB instance? Without this connection, none of your queries matter. This lesson strips away the mystery, giving you the exact commands and mistake-prone details to bridge Python and MongoDB so you can start storing and fetching real documents.

The problem this lesson solves

Every MongoDB tutorial assumes you can already talk to the database. But when you try on your own, you're hit with ServerSelectionTimeoutError, wrong ports, or the dreaded "Connection refused." Even if you know MongoDB is installed, you might not know which package to install, what connection string to use, or how to verify the connection works.

This is a classic wiring problem: the database runs in one process, your Python script runs in another, and they need a handshake. Without this lesson, you'll waste hours guessing. With it, you'll connect in under five minutes and move on to actually building your application.

Core concept / mental model

Think of MongoDB as a hotel. The database server (mongod) is the hotel building — it accepts guests (connections) at a specific front desk (the port, default 27017). The PyMongo driver is your concierge: it knows the hotel's address, knocks on the door, and once welcomed, can fetch anything from the rooms (collections).

PyMongo's MongoClient is not a single connection. It manages a connection pool — a set of reusable sockets to the server. This is key: you create one MongoClient object and reuse it across your app. Creating a new client for every query would be like calling a taxi for every block you walk — expensive and slow.

Pro tip: The default port for MongoDB is 27017. If you see 28017, that's usually the web interface, not the database protocol.

How it works step by step

1. Install PyMongo in your Python environment: pip install pymongo. You might also want dnspython for SRV connection strings (like MongoDB Atlas).
2. Start MongoDB in the background or another terminal: the mongod service must be running. On macOS/Linux, brew services start mongodb-community or sudo systemctl start mongod; on Windows, run the mongod.exe binary.
3. Build your connection string: typically mongodb://localhost:27017/ for a local instance. For Atlas, it looks like mongodb+srv://user:pass@cluster.mongodb.net/.
4. Create a MongoClient: client = MongoClient(connection_string). This doesn't actually connect yet — it's lazy, the real handshake happens on your first operation.
5. Access your database and collections: use client['mydatabase'] and db['mycollection'] — no need to pre-create them.
6. Test the connection with client.admin.command('ping') and then perform operations like insert_one and find.

Pro tip: Always use a single MongoClient per application process. MongoDB drivers are thread-safe and the client manages its own connection pool for you.

Hands-on walkthrough

Let's build a complete example from scratch.

Step 1: Install PyMongo

pip install pymongo

If you're using MongoDB Atlas (cloud), also install dnspython:

pip install dnspython

Step 2: Ensure MongoDB is running

Before you write any Python, verify the server is up. A quick mongosh test prints ok: 1 if the server is healthy:

mongosh --eval "db.runCommand({ping:1})"

If you get an error, your mongod process isn't running. Start it via your system's service manager.

Step 3: Connect from Python

Save this as connect.py:

from pymongo import MongoClient

# Step 1: Build the connection string
connection_string = "mongodb://localhost:27017/"

# Step 2: Create a client (lazy connection)
client = MongoClient(connection_string)

# Step 3: Verify the connection by pinging the server
client.admin.command("ping")
print("Connected to MongoDB!")

Expected output:

Connected to MongoDB!

If you see a ServerSelectionTimeoutError, check that MongoDB is actually running and that the host/port are correct.

Step 4: Read and write a document

Now let's make it useful. We'll insert a user document and immediately read it back:

from pymongo import MongoClient

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

db = client["shop"]          # database (created on first use)
users = db["users"]          # collection (also lazy)

# Insert a document
result = users.insert_one({"name": "Ada", "role": "admin"})
print("Inserted id:", result.inserted_id)

# Read it back
user = users.find_one({"name": "Ada"})
print("Found:", user)

Expected output:

Inserted id: 64b6f1c2d3e4f5a6b7c8d9e0
Found: {'_id': ObjectId('64b6f1c2d3e4f5a6b7c8d9e0'), 'name': 'Ada', 'role': 'admin'}

Step 5: Handle authentication

For production, you'll likely have credentials. Here's a connection string with a username and password (URL-encoded if necessary):

from pymongo import MongoClient

# Note: escape special characters in password using URL encoding
conn = "mongodb://admin:mysecretpassword@localhost:27017/"
client = MongoClient(conn)

# If your auth DB is not the default 'admin', specify it
client = MongoClient(conn, authSource="admin")

client.admin.command("ping")
print("Authenticated and connected!")

Pro tip: Keep your connection string in an environment variable, never hardcode it. Use os.environ["MONGODB_URI"] in production.

Compare options / when to choose what

Alternative connection approaches:

• Environment variables: Store connection strings in .env files instead of code.
• URI builder libraries: Use pymongo.uri_parser or Django/Flask extensions to build connection strings dynamically.
• Other drivers: If you're not using Python, the official drivers for Node.js, Go, etc., use the same MongoDB connection protocol.

Troubleshooting & edge cases

Common pitfalls:

• Forgetting to install dnspython for SRV URIs (Atlas).
• Creating a new MongoClient inside every request — leaks sockets.
• Using client = MongoClient("localhost") without the port — defaults to 27017, which is fine, but a common mistake is using localhost vs 127.0.0.1 in IPv6 environments.

What you learned & what's next

Now you can connect PyMongo to a running MongoDB instance — you've installed the driver, verified the server is alive, performed insert and find operations, and handled authentication and common errors. That's the foundation for every subsequent MongoDB lesson.

Next up in the MongoDB track: you'll dive into CRUD operations in depth — crafting filters, sorting results, and updating documents efficiently. With a working connection, you're ready to manipulate real data with confidence.