Setup: MongoDB, mongosh and Compass
Install MongoDB Community Server, mongosh and Compass on Windows with winget or on a Mac with Homebrew, check that the server is running in the background, and connect to it with mongosh at mongodb://localhost:27017.
Novice · MongoDB · Database · Updated
After this lesson you can
- Name the three pieces of a local MongoDB setup, the server, mongosh and Compass, and say what each one does
- Check that the MongoDB server is running and that mongosh connects to it at mongodb://localhost:27017
Key takeaways
- MongoDB Community Server is the free database itself. It runs in the background with no window, waiting for programs to connect.
- mongosh, the MongoDB Shell, is where you type commands and read the database's answers. Compass shows the same data in windows you click through.
- On Windows the server runs as a Windows service, which Get-Service MongoDB checks. On a Mac, brew services runs it and brew services list checks it.
- mongosh on its own connects to mongodb://127.0.0.1:27017, MongoDB on this computer at its usual port, and shows the version it found.
Every developer who works on an app with MongoDB keeps a copy of MongoDB on their own computer, where they can try a query or break something without touching anyone's real data. This lesson sets that up, once, in about twenty minutes. It works offline and needs no account. Windows and macOS are both shown: follow the part for your computer. If you can't install programs on your computer, Another Way: A Free Cluster on MongoDB Atlas is the way in instead.
Three pieces, three jobs
Think of a restaurant. The kitchen does the real work out of sight; the counter is where you place an order and get it back; the window lets you look in and watch.
| Piece | What it does | Like |
|---|---|---|
| MongoDB Community Server | The free edition of the database itself. It runs in the background, with no window, waiting for programs to connect. | The kitchen |
| mongosh | The MongoDB Shell: you type a command, press Enter and read the database's answer. From here on, "the shell". | The counter |
| MongoDB Compass | A desktop app that shows the same databases and documents in windows you click through | The window |
MongoDB 9.0 needs Windows 11, or macOS 15 or later. The course was checked with MongoDB 9.0, mongosh 2.14 and Compass 1.53.
Install them
On Windows
Open the Terminal app (open the Start menu and type terminal). Type each command, press Enter, and click Yes if Windows asks whether the app may make changes:
winget install -e --id MongoDB.Server
winget install -e --id MongoDB.Shell
winget install -e --id MongoDB.Compass.Full
winget is the Windows Package Manager: it installs programs by name. The first line installs the server as a Windows service, a program Windows starts by itself every time the computer starts, so MongoDB is always ready. The shell comes separately, in the second line. Use MongoDB.Compass.Full as shown: winget also lists a MongoDB.Compass.Community, but it's stuck on a much older Compass.
No winget? mongodb.com's download page for MongoDB Community Server has a Windows installer: keep Install MongoD as a Service and Install MongoDB Compass ticked. mongosh has its own download page there.
On a Mac
On a Mac, MongoDB is installed with Homebrew, the package manager for macOS (brew.sh shows how to install it). MongoDB keeps its own list of programs for Homebrew, called a tap. In the Terminal app (in Applications > Utilities), add the tap, mark it as trusted, and install MongoDB 9.0:
brew tap mongodb/brew
brew trust mongodb/brew
brew update
brew install mongodb-community@9.0
That installs the server and mongosh together. Start the server, and install Compass:
brew services start mongodb-community@9.0
brew install --cask mongodb-compass
brew services start runs the server in the background, and starts it again each time you sign in. If macOS says mongod (the server's program) can't be verified, open System Settings > Privacy & Security and click Open Anyway beside the message.
Is the server running?
On Windows, ask about the service by its name, MongoDB, in the Terminal app (PowerShell):
Get-Service MongoDB
Status Name DisplayName
------ ---- -----------
Running MongoDB MongoDB Server (MongoDB)
Running is what you want. If it says Stopped, open the Terminal app as an administrator (right-click it in the Start menu, Run as administrator) and run Start-Service MongoDB.
On a Mac, brew services list lists what Homebrew runs in the background, and the mongodb-community line should say started. If it doesn't, run the brew services start line again.
mongosh answers
Close VS Code if it's open, then open it again, so its terminal can find the programs you installed. Open its terminal with Terminal > New Terminal, and start the shell:
mongosh
The shell connects and prints a few lines about the connection first:
Current Mongosh Log ID: 6afc99e3f6b2618da968456d
Connecting to: mongodb://127.0.0.1:27017/?directConnection=true&serverSelectionTimeoutMS=2000&appName=mongosh+2.14.2
Using MongoDB: 9.0.8
Using Mongosh: 2.14.2
Connecting to is the address it used: 127.0.0.1 is another way to write localhost, this computer, and 27017 is the port, the numbered door MongoDB listens at. With nothing after mongosh, the shell always tries mongodb://localhost:27017. Using MongoDB is the server's version: any 9.0 works (winget installs 9.0.4). Your log ID will be different.
A few notes follow, one saying that access control isn't enabled, meaning there's no password. That's fine on your own computer: out of the box, MongoDB only accepts connections from programs on this computer. Then comes the prompt, test>, where the shell waits for a command. Type exit and press Enter to leave.
Each exercise's tests start a throwaway MongoDB of their own, so they never touch your databases. With MongoDB installed, they use the program you installed here. Without it, the first npm test downloads MongoDB for the tests: about 950 MB on Windows, about 180 MB on a Mac, once per computer.
If something goes wrong
| What you see | What it means, and what to do |
|---|---|
The term 'mongosh' is not recognized (Windows) or zsh: command not found: mongosh (Mac) |
The terminal can't find the shell: it isn't installed, or VS Code was open while it installed. Close VS Code completely, open it again, and retry. |
MongoNetworkError: connect ECONNREFUSED 127.0.0.1:27017 |
The shell is fine, but no server is answering. Check it's running (above) and start it. |
Get-Service says it can't find a service named MongoDB |
The server was installed without the service. Install it again with the winget line above. |
Check yourself
2 questions to try on the lesson page.
So what
You now have your own MongoDB, a shell to talk to it and a window to look into it: a safe place to try every query in this course before it ever touches real data.