Upon completion of this lesson, you will be able to:
In contemporary software systems, especially those dealing with large-scale, flexible, and heterogeneous data like healthcare, patient, shopping cart, or employment records, a non-relational approach to database design is often more suitable than traditional relational databases. MongoDB is one of the most widely used NoSQL databases, and it is particularly well-suited for applications that require rapid development, horizontal scalability, and the ability to handle diverse data structures.
In this tutorial, we will provide installation instructions for both Windows and MacOS, and demonstrate how to connect to MongoDB from R and Python.
MongoDB is a document-oriented NoSQL database. Instead of storing data in tables with rows and columns like in relational databases, MongoDB stores data in flexible, JSON-like documents called BSON (Binary JSON). These documents can contain nested structures, arrays, and varying sets of fields, making MongoDB particularly useful when dealing with unstructured or semi-structured data, such as patient health records, diagnostic histories, and lab results.
One of the key differences between MongoDB and relational databases lies in the schema. A relational database enforces a strict schema — every row in a table must adhere to the same structure. In contrast, MongoDB collections (the equivalent of tables) allow documents (rows) with different structures, which supports schema-less development and evolving data requirements.
MongoDB is distributed in two main editions: Community Server (free, open-source) and Enterprise. This lesson uses the Community Server, which is sufficient for learning, experimentation, prototyping, and small applications. We tested the instructions below on MacOS Sequoia and Windows 11 – let us know if you experience any differences or difficulties.
Step 1 — Download the installer.
Navigate to https://www.mongodb.com/try/download/community. Under the “MongoDB Community Server” tab, select:
msiClick Download.
Step 2 — Run the MSI installer.
Double-click the downloaded .msi file. Work through the setup wizard:
mongosh).MongoDB, and the default data directory is C:\Program Files\MongoDB\Server\<version>\data\.Click Install, then Finish.
Step 3 — Verify the service is running.
Open PowerShell as Administrator and run:
You should see Status: Running. If the service is not running, start it with:
Step 4 — Add MongoDB binaries to your PATH (if not done automatically).
The installer typically adds C:\Program Files\MongoDB\Server\<version>\bin to your system PATH. Verify this by opening a new PowerShell window and typing:
If the command is not recognized, add the bin directory manually:
Path and click Edit.C:\Program Files\MongoDB\Server\<version>\bin (replace <version> with your installed version number, e.g., 7.0).Step 5 — Test the connection.
Install mongosh, a separate activity on Windows, from https://www.mongodb.com/try/download/shell. After completing the installation, restart your computer. Then, launch PowerShell, and type:
You should see the MongoDB shell prompt (test>). Type exit to leave the shell.
There are two supported methods on macOS: using Homebrew (recommended) or downloading the tarball manually. This lesson covers Homebrew, which handles dependencies and PATH configuration automatically.
Step 1 — Install Homebrew (if not already installed).
Open Terminal and run:
Follow the on-screen prompts, particularly those that explain how to add the brew command to your zsh default path. After installation and changing your path environment variable, run brew --version to confirm it is working.
Step 2 — Add the MongoDB Homebrew tap.
MongoDB is not in Homebrew’s default formula repository. Add MongoDB’s official tap:
Step 3 — Install MongoDB Community.
Homebrew installs MongoDB, the mongosh shell, and creates the necessary directories. The default data directory is /opt/homebrew/var/mongodb on Apple Silicon Macs or /usr/local/var/mongodb on Intel Macs. The log file is at /opt/homebrew/var/log/mongodb/mongo.log (Apple Silicon) or /usr/local/var/log/mongodb/mongo.log (Intel).
Step 4 — Start the MongoDB service.
To verify it is running:
You should see mongodb-community with status started.
Step 5 — Test the connection.
You should see the MongoDB shell prompt. Type exit to leave. If you did not see the MongoDB shell prompt, then your installation was not successful.
To verify that the service is running and that we can connect to the database, we will demonstrate how to connect to MongoDB from R.
mongolite is the primary R package for interacting with MongoDB. It wraps the mongo-c-driver and provides a clean interface for CRUD operations.
After installation of the mongolite package, be sure to load the package with:
The central object in mongolite is the mongo connection object, created by calling mongo(). Its primary arguments are:
| Argument | Description |
|---|---|
collection |
The name of the MongoDB collection (analogous to a table in a relational database). |
db |
The name of the database. MongoDB creates it automatically if it does not exist. |
url |
The MongoDB connection string. The default is "mongodb://localhost" (port 27017). |
Basic connection to a local MongoDB instance:
library(mongolite)
# Connect to a collection named "students" in a database named "university"
con <- mongo(
collection = "students",
db = "university",
url = "mongodb://localhost:27017"
)This line does not open a persistent socket immediately — it configures the connection. The actual connection is established on the first operation. If MongoDB is not running, you will receive an error at that point.
Verify the connection is live:
A return value of 0 with no error confirms a successful connection.
We can connect to MongoDB from Python rather than R. A few notes on the equivalences between the two:
Package: mongolite in R maps to pymongo in Python. Install it with pip install pymongo if you have not already.
Connection structure: mongolite collapses the client, database, and collection into a single mongo() call. In pymongo these are three distinct steps – you create a MongoClient, select a database from it by name, then select a collection from that database by name. The resulting con object in Python is directly equivalent to the con object in R.
Document count: con$count() in R maps to con.count_documents({}) in Python. The empty dict {} is the query filter, meaning “match all documents,” which is the same behavior as calling count() with no arguments in mongolite. The older con.count() method exists in pymongo but has been deprecated and should not be used.
from pymongo import MongoClient
# Connect to a collection named "students" in a database named "university"
client = MongoClient("mongodb://localhost:27017")
db = client["university"]
con = db["students"]
# Returns the number of documents in the collection (0 if empty, error if unreachable)
print(con.count_documents({}))Windows
| Mistake | Symptom | Resolution |
|---|---|---|
| Installing over an existing version without uninstalling first | Service fails to start; conflicting data directory versions | Uninstall the old version via Add/Remove Programs, delete the old data directory, then reinstall. |
| Not running the installer as Administrator | Permission errors during service registration | Right-click the .msi file and select Run as administrator. |
Missing PATH entry for the bin directory |
mongosh is not recognized in PowerShell |
Manually add C:\Program Files\MongoDB\Server\<version>\bin to the system PATH and restart the terminal. |
| Firewall blocking port 27017 | Remote connections refused | Open Windows Defender Firewall and add an inbound rule for TCP port 27017. For local-only development, this is not necessary. |
| Data directory does not exist | mongod crashes on startup |
The installer creates C:\Program Files\MongoDB\Server\<version>\data automatically, but if you specified a custom path, create that directory manually before starting the service. |
macOS
| Mistake | Symptom | Resolution |
|---|---|---|
Skipping brew tap mongodb/brew |
brew install mongodb-community fails with “No available formula” |
Always tap the MongoDB repository first. |
| Using an outdated Homebrew before tapping | Formula version conflicts | Run brew update before tapping and installing. |
| Forgetting to start the service | mongosh hangs or refuses connection |
Run brew services start mongodb-community. |
| Homebrew installed in non-standard location on Apple Silicon | mongosh not found in PATH |
Apple Silicon uses /opt/homebrew/bin. Add it to your shell profile: export PATH="/opt/homebrew/bin:$PATH". |
| macOS Gatekeeper blocking binaries | “Cannot open because developer cannot be verified” | Open System Settings → Privacy & Security and allow the blocked binary, or install Homebrew’s version which is signed. |
MongoDB offers a flexible and schema-less data model that is commonly used for complex, nested, and heterogeneous data structures. This lesson explained how to install MongoDB on Windows and MacOS and connect to a MongoDB instance from R as well as Python.
We acknowledge the use of Claude 4.6 (Sonnet) during the preparation of this lesson. We also thank Uday Sonawane for testing the installation instructions on Windows.