MongoDB Atlas Tutorial: Free Cluster, Compass & Python (2026)

MongoDB Atlas hosts MongoDB databases in the cloud. This guide walks through an Atlas Free cluster, safe network access, MongoDB Compass, and a small Python connection test with PyMongo. You can follow the Compass steps on their own if you do not need application code.

The Atlas setup terms and driver links were checked on 21 October 2026. Atlas may change labels or availability, so use the current Connect dialog and the official documentation when a menu differs.

What the Atlas Free cluster is for

Atlas Free clusters were formerly called M0. MongoDB describes them as a learning and small proof-of-concept option. Current limits include one Free cluster per project, capped resources, and automatic pausing after 30 days with no connections. Check the published limits before putting data you care about there.

Create a Free cluster in Atlas

Review current Free cluster limits

1. Create a project and Free cluster

Sign in to MongoDB Atlas and open or create a project. On the project's database page, choose Create, select the Free or M0 option, then choose a cloud provider and a region shown as available for Free clusters. Pick a region reasonably close to the app that will use the database, name the cluster, and create it. Do not select a paid tier unless you intend to use one.

Atlas asks you to create a database user and allow a client IP address as part of the setup. These are database connection credentials and network rules; they are separate from the email and password you use to sign in to Atlas.

2. Set database access safely

Create a strong database-user password and save it in a password manager. Give the user only the database permissions required for the exercise. For the example below, use read/write access to the atlas_demo database if the role picker offers that scope; avoid broad administrator roles for an application account.

In Network Access or the connection wizard, add your current public IP address. Home and office IPs can change, so update the entry if your connection stops working. Avoid 0.0.0.0/0: that allows connections from anywhere on the public internet and can expose the deployment to unauthorized access.

MongoDB's IP access-list security guide

3. Connect with MongoDB Compass

Install MongoDB Compass from the official download page. In Atlas, open your cluster's Connect dialog, choose Compass, and copy the URI Atlas provides. If the dialog asks, create the database user and add your IP address first. In Compass, paste the URI, replace any username or password placeholders, and connect.

Use the URI Atlas gives you rather than guessing the hostname or removing its options. If a username or password contains reserved characters such as @, /, ?, or #, encode them for a connection URI. Never share the URI, commit it to Git, or put it in a public screenshot: it contains access credentials.

MongoDB Atlas Compass connection steps

Once Compass connects, expand the deployment to browse databases and collections. Create a small practice database and collection if prompted. A successful connection does not mean the cluster is private from every risk; keep the IP list narrow and the database user's role limited.

4. Test a Python connection with PyMongo

If you want to connect from a Python app, first install the current PyMongo driver:

python -m pip install pymongo

Copy the driver URI from Atlas and keep it in an environment variable. The following examples show the variable name and shape; use the complete URI from your own Atlas Connect dialog.

# Windows PowerShell
$env:MONGODB_URI = "mongodb+srv://<db-user>:<encoded-password>@<cluster-host>/?retryWrites=true&w=majority"

# macOS or Linux shell
export MONGODB_URI='mongodb+srv://<db-user>:<encoded-password>@<cluster-host>/?retryWrites=true&w=majority'

Save this as test_atlas.py. It checks the connection, then writes and reads one harmless sample document using an upsert so rerunning the script does not create duplicates:

import os
from pymongo import MongoClient
from pymongo.server_api import ServerApi

uri = os.environ["MONGODB_URI"]

with MongoClient(uri, server_api=ServerApi("1")) as client:
    client.admin.command("ping")
    collection = client["atlas_demo"]["connection_checks"]
    collection.update_one(
        {"_id": "hello-atlas"},
        {"$set": {"message": "Connected from PyMongo"}},
        upsert=True,
    )
    print(collection.find_one({"_id": "hello-atlas"}))

Run the test from the same terminal where you set MONGODB_URI:

python test_atlas.py

The MongoDB driver documentation explains how to create a MongoClient and use an Atlas URI. For a real app, load secrets from your deployment's secret manager rather than storing credentials in source code or a committed .env file.

PyMongo Atlas connection guide

Troubleshooting common connection errors

• IP not allowed: check Network Access and confirm your current public IP or app host's outbound IP is listed. The Atlas UI login IP list is not the same thing as a cluster database user's credentials.

• Authentication failed: use the database username, not your Atlas website login. Recheck the password and percent-encode reserved characters in the URI.

• Server selection timeout: confirm the cluster is running, the URI is copied from Atlas, and your firewall allows outbound access to Atlas on the documented ports.

• Free option not shown: check that you selected a supported provider and region. Review the current Atlas cluster page before creating anything that may incur a charge.

Free clusters can pause after extended inactivity and are designed for learning or small experiments. For an application with users or important data, review Atlas' current limits, backup options, security settings, and paid tiers before relying on it.

Connect to an Atlas cluster: official guide