Choose a Connection Target

Overview

In this guide, you can learn how to use a connection string and MongoClient object to connect to different types of MongoDB deployments.

Atlas

To connect to a MongoDB deployment on Atlas, include the following elements in your connection string:

• URL of your Atlas cluster

• MongoDB username

• MongoDB password

Then, pass your connection string to the MongoClient constructor.

When you connect to Atlas, we recommend using the Stable API client option to avoid breaking changes when Atlas upgrades to a new version of MongoDB Server. To learn more about the Stable API feature, see the Stable API page.

The following code shows how to use PyMongo to connect to an Atlas cluster. The code also uses the server_api option to specify a Stable API version.

from pymongo import MongoClient
from pymongo.server_api import ServerApi
# Replace the placeholder with your Atlas connection string
uri = "<connection string>"
# Create a MongoClient with a MongoClientOptions object to set the Stable API version
client = MongoClient(uri, server_api=ServerApi(
    version='1', strict=True, deprecation_errors=True))
try:
    # Connect the client to the server (optional starting in v4.7)
    client.connect()
    # Send a ping to confirm a successful connection
    client.admin.command({'ping': 1})
    print("Pinged your deployment. You successfully connected to MongoDB!")
finally:
    # Ensures that the client will close when you finish/error
    client.close()

Local Deployments

To connect to a local MongoDB deployment, use localhost as the hostname. By default, the mongod process runs on port 27017, though you can customize this for your deployment.

The following code shows how to use PyMongo to connect to a local MongoDB deployment:

from pymongo import MongoClient
uri = "mongodb://localhost:27017/"
client = MongoClient(uri)

Replica Sets

To connect to a replica set, specify the hostnames (or IP addresses) and port numbers of the replica-set members in your connection string.

If you aren't able to provide a full list of hosts in the replica set, you can specify one or more of the hosts in the replica set and instruct PyMongo to perform automatic discovery to find the others. To instruct the driver to perform automatic discovery, perform one of the following actions:

• Specify the name of the replica set as the value of the replicaSet parameter.

• Specify false as the value of the directConnection parameter.

• Specify more than one host in the replica set.

In the following example, the driver uses a sample connection URI to connect to the MongoDB replica set sampleRS, which is running on port 27017 of three different hosts, including host1:

from pymongo import MongoClient
uri = "mongodb://host1:27017/?replicaSet=sampleRS"
client = MongoClient(uri)

from pymongo import MongoClient
client = MongoClient("mongodb://<hostname>:<port>",
                     directConnection=True)

from pymongo import MongoClient
uri = ("mongodb://<hostname>:<port>/?"
       "directConnection=true")
client = MongoClient(uri)

Troubleshooting

pymongo.errors.ConfigurationError: Server at localhost:27017 reports wire version 6, but this version of PyMongo requires at least 7 (MongoDB 4.0).

API Documentation

To learn more about creating a MongoClient object in PyMongo, see the following API documentation:

• MongoClient