Install MongoDB, mongosh & Compass

Before you can store a single document you need a MongoDB server to talk to and a tool to talk to it with. You have two good options: install the free Community Server on your own computer, or create a free Atlas cluster in the cloud. Either way you will use the same two client tools: the MongoDB Shell (mongosh) for typing commands and MongoDB Compass for browsing data visually.

In this lesson you will set up one server, connect to it from mongosh and Compass, and check that everything works. Many learners do both: a local server for practice and Atlas for projects they want to share.

The pieces you will install

The server is the program that stores data and answers queries. mongosh and Compass are clients: they connect to a server, send it commands and show the results.

Option 1: Community Server on your computer

Download the server from the official download centre at mongodb.com/try/download/community, choose version 9.0 and your platform.

Windows. MongoDB 9.0 supports 64-bit Windows 11 and Windows Server 2022. Run the .msi installer, choose the Complete setup, and keep the option to install MongoDB as a Windows service so that the server starts automatically. The installer also offers to install Compass; keep that ticked. The server program is placed in C:\Program Files\MongoDB\Server\9.0\bin, and its settings file is mongod.cfg in the same folder. To stop or start the service later, open PowerShell as Administrator:

net stop MongoDB
net start MongoDB

macOS. The simplest route is Homebrew, using MongoDB's own tap:

brew tap mongodb/brew
brew install mongodb-community
brew services start mongodb-community

Linux. On Ubuntu and other supported distributions you add MongoDB's package repository (the exact lines for your release are on the official install page), then install the mongodb-org package and start the mongod service with sudo systemctl start mongod.

Docker. If you already use Docker, one command starts a disposable server: docker run --name mongodb -p 27017:27017 -d mongodb/mongodb-community-server:latest.

Whichever way you install, the server listens on port 27017 and, by default, only accepts connections from the same computer (127.0.0.1). That default is a good safety measure; you will learn how to open it up securely in Security: Users, Roles & Network Access.

Option 2: a free Atlas cluster

Atlas runs MongoDB for you in the cloud. Its Free cluster (formerly called M0) costs nothing, never expires and is meant for learning and small prototypes. It has limits: about 0.5 GB of storage, 500 connections and 100 operations per second, and it runs the MongoDB version Atlas chooses (currently 8.0), so a few 9.0-only features need a local server or a paid cluster.

1. Sign up at mongodb.com/atlas and create a project.
2. Click Create, pick the Free option, and choose a provider and a region close to you, such as Mumbai.
3. Create a database user with a username and a strong password. This is not your Atlas login.
4. Add your current IP address to the IP access list. Atlas refuses connections from any address that is not on the list.
5. Open Connect, choose the shell, and copy the connection string. It starts with mongodb+srv://.

Connect with mongosh

mongosh is a separate download from mongodb.com/try/download/shell (the server installer does not include it). Make sure its folder is on your PATH, open a new terminal and type mongosh. With no arguments it connects to a local server on port 27017:

mongosh

Current Mongosh Log ID: 6ae41c2f9b7d3e5a8c1f4062
Connecting to:          mongodb://127.0.0.1:27017/?directConnection=true&serverSelectionTimeoutMS=2000&appName=mongosh+2.14.0
Using MongoDB:          9.0.4
Using Mongosh:          2.14.0

For mongosh info see: https://www.mongodb.com/docs/mongodb-shell/

test>

Your log ID and version numbers will differ. You may also see a few startup warnings, for example that access control is not enabled; that is normal on a practice machine. The prompt test> shows the current database. MongoDB starts you in a database called test, which does not really exist until you store something in it.

For Atlas, pass your connection string and username. mongosh then asks for the password, so it never appears in your terminal history:

mongosh "mongodb+srv://cluster0.ab1cd.mongodb.net/" --username priya

Your first commands

Try these three commands. db.version() reports the server version, the ping command checks that the server answers, and show dbs lists the databases:

db.version()
db.runCommand({ ping: 1 })
show dbs

9.0.4
{ ok: 1 }
admin   40.00 KiB
config  72.00 KiB
local   40.00 KiB

admin, config and local are system databases that MongoDB uses internally; leave them alone. The sizes on your machine will be different. Type exit (or press Ctrl+D) to leave the shell.

mongosh is a full JavaScript environment, so you can use variables, loops and functions, and press the Tab key to complete method names. Press the up arrow to bring back earlier commands.

Connect with Compass

Open Compass and add a new connection. For a local server the address is mongodb://localhost:27017; for Atlas, paste the same mongodb+srv:// string you used in mongosh, including your username. Once connected, the left panel lists databases and collections. For each collection you can browse and edit documents, filter them with a query, view the indexes, see an analysis of the fields, build aggregation pipelines step by step, and read query plans. Compass also has a built-in mongosh panel at the bottom of the window, which is handy if the separate shell is not on your PATH.

Common mistakes

• ECONNREFUSED 127.0.0.1:27017. The server is not running. Start the service (net start MongoDB, brew services start mongodb-community or sudo systemctl start mongod) and try again.
• Atlas connection times out. Your IP address is not on the access list, or it changed since you added it. Add the current address in Atlas under network access.
• Special characters in the password. Characters such as @, : or / break a connection string. Let mongosh prompt for the password, or percent-encode it (@ becomes %40).
• mongosh is not recognised. The shell is a separate install. Install it and open a new terminal so the updated PATH is loaded.

Key points

• You need a server (local Community Server or an Atlas cluster) and a client (mongosh, Compass or a driver).
• The local server listens on port 27017 and accepts only local connections by default.
• The Atlas Free cluster needs a database user and your IP address on the access list.
• mongosh is installed separately; start it with mongosh or mongosh "<connection string>".
• db.version(), db.runCommand({ ping: 1 }) and show dbs confirm that the connection works.
• Compass is a visual client with a built-in shell, a pipeline builder and an index view.

db.version()
show dbs