Python Quick Start

Use PyMongo to connect to DocumentDB, verify authentication and TLS, and run your first document queries from Python.

Prerequisites

Python 3.9 or later
pip
A local DocumentDB instance from Docker Quick Start or Linux Packages Quick Start
Optional: mongosh for independent connection checks

Start DocumentDB first

For the fastest local setup, start DocumentDB Local with Docker:

docker run -dt --name documentdb \
  -p 10260:10260 \
  ghcr.io/documentdb/documentdb/documentdb-local:latest \
  --username <YOUR_USERNAME> \
  --password <YOUR_PASSWORD>

If you prefer a host installation instead of Docker, use Linux Packages Quick Start for the PostgreSQL extension package and run the gateway from source.

DocumentDB Local uses a self-signed certificate by default, so the quickest local PyMongo connection uses tlsAllowInvalidCertificates=true.

Create a virtual environment (optional)

python3 -m venv .venv
source .venv/bin/activate

If you do not use a virtual environment, run the next commands with the Python interpreter you plan to use for your app.

Install PyMongo

python -m pip install pymongo

PyMongo already includes the bson package it needs. Do not install the separate bson package from PyPI.

Connect and run your first queries

Create a quickstart.py file:

from pymongo import MongoClient

uri = (
    "mongodb://<YOUR_USERNAME>:<YOUR_PASSWORD>@localhost:10260/"
    "?tls=true&tlsAllowInvalidCertificates=true"
)

client = MongoClient(uri)

try:
    client.admin.command("ping")

    db = client["quickstart"]
    movies = db["movies"]

    movies.delete_many({})
    movies.insert_many(
        [
            {"title": "The Matrix", "year": 1999, "genres": ["sci-fi", "action"]},
            {"title": "Dune", "year": 2021, "genres": ["sci-fi", "adventure"]},
            {"title": "Arrival", "year": 2016, "genres": ["sci-fi", "drama"]},
        ]
    )

    movies.create_index("title")

    for movie in movies.find(
        {"year": {"$gte": 2000}},
        {"_id": 0, "title": 1, "year": 1},
    ).sort("year", -1):
        print(movie)
finally:
    client.close()

Run the script:

python quickstart.py

You should see the recent movie documents printed after a successful ping.

Explore the built-in sample data

If you started with DocumentDB Local sample data, add this snippet after client.admin.command("ping"):

for user in client["sampledb"]["users"].find(
    {},
    {"_id": 0, "name": 1, "email": 1},
).limit(3):
    print(user)

Use a trusted local certificate instead

If you want certificate validation instead of tlsAllowInvalidCertificates=true, copy the generated certificate from the container and pass it to MongoClient.

docker cp documentdb:/home/documentdb/gateway/pg_documentdb_gw/cert.pem ~/documentdb-cert.pem

client = MongoClient(
    "mongodb://<YOUR_USERNAME>:<YOUR_PASSWORD>@localhost:10260/?tls=true",
    tlsCAFile="/absolute/path/documentdb-cert.pem",
)

Troubleshooting and debugging

If the Python quick start does not work on the first try:

Verify your local DocumentDB instance is running before you start Python
If you used Docker, check docker ps --filter "name=documentdb" and docker logs documentdb
If you used a host-built gateway, confirm the gateway process is running and listening on port 10260
If Python cannot import pymongo, verify the active interpreter with python -c "import sys; print(sys.executable)" and reinstall with python -m pip install pymongo
If you see TLS or certificate errors, either use the default local self-signed flow with tlsAllowInvalidCertificates=true or switch to a trusted local certificate with tlsCAFile
Use Mongo Shell Quick Start to validate the endpoint independently of your application code