Section 2: Installation

⚡ MongoDB Shell (mongosh) Installation

Complete guide to install the modern MongoDB Shell on Windows, macOS, and Linux

Home › Section 2: Installation › MongoDB Shell Installation
3 Platforms Supported
2min Installation Time
100% Free & Open Source
JS JavaScript Shell
📖

What is MongoDB Shell?

The modern JavaScript interface for MongoDB

💡 MongoDB Shell (mongosh)

mongosh is the modern, JavaScript-based MongoDB Shell that replaced the legacy mongo shell. It provides an enhanced command-line interface for interacting with MongoDB databases, with better syntax highlighting, improved autocomplete, and full JavaScript support.

🎨
Syntax Highlighting
Beautiful colored output makes code easier to read and debug
⌨️
Smart Autocomplete
Intelligent suggestions for commands, collections, and fields
🔄
Modern JavaScript
Full ES6+ support with async/await, arrow functions, and more
📦
npm Packages
Import and use npm packages directly in the shell
🔍
Better Errors
Clear, detailed error messages help troubleshoot issues
⚡
Fast & Lightweight
Quick startup and responsive command execution
⚠️ Legacy vs Modern Shell
  • Old: mongo (deprecated as of MongoDB 5.0)
  • New: mongosh (modern, actively maintained)
  • Recommendation: Always use mongosh for new projects
🪟

Windows Installation

Two installation methods

1
Method 1: MSI Installer (Recommended)

Step 1: Download the Windows MSI installer:

Download mongosh for Windows

Step 2: Run the installer:

  1. Double-click the downloaded .msi file
  2. Click "Next" through the installation wizard
  3. Accept the license agreement
  4. Choose installation location (default is fine)
  5. Click "Install"
  6. Click "Finish" when complete
✅ Installed! The installer automatically adds mongosh to your system PATH.
2
Method 2: Chocolatey Package Manager

If you have Chocolatey installed, you can install mongosh with one command:

PowerShell (Admin)
PS> choco install mongodb-shell
Installing the following packages: mongodb-shell ... The install of mongodb-shell was successful.
🍎

macOS Installation

Using Homebrew or manual install

1
Method 1: Homebrew (Recommended)

The easiest way to install mongosh on macOS:

Terminal
# Install mongosh $ brew install mongosh
==> Downloading mongosh ==> Pouring mongosh--2.1.1.arm64_sonoma.bottle.tar.gz 🍺 /opt/homebrew/Cellar/mongosh/2.1.1: 6 files, 50.2MB
# Verify installation $ mongosh --version
2.1.1
✅ Done! mongosh is now installed and ready to use.
2
Method 2: Manual Installation

Step 1: Download the macOS package:

Download mongosh for macOS

Step 2: Extract and install:

Terminal
# Navigate to Downloads $ cd ~/Downloads # Extract the archive $ tar -zxvf mongosh-2.1.1-darwin-x64.tgz # Move to /usr/local/bin $ sudo cp mongosh-2.1.1-darwin-x64/bin/mongosh /usr/local/bin/ # Make executable $ sudo chmod +x /usr/local/bin/mongosh
🐧

Linux Installation

Ubuntu/Debian and RHEL/CentOS

1
Ubuntu / Debian
Terminal
# Download and install $ wget https://downloads.mongodb.com/compass/mongosh-2.1.1-linux-x64.tgz # Extract $ tar -zxvf mongosh-2.1.1-linux-x64.tgz # Move to /usr/local/bin $ sudo cp mongosh-2.1.1-linux-x64/bin/mongosh /usr/local/bin/ # Make executable $ sudo chmod +x /usr/local/bin/mongosh # Verify $ mongosh --version
2.1.1
2
RHEL / CentOS / Fedora
Terminal
# Download RPM package $ wget https://downloads.mongodb.com/compass/mongosh-2.1.1-x86_64.rpm # Install with yum $ sudo yum install mongosh-2.1.1-x86_64.rpm # OR with dnf (Fedora/RHEL 9) $ sudo dnf install mongosh-2.1.1-x86_64.rpm # Verify $ mongosh --version
2.1.1
✓

Verify Installation

Test mongosh is working

Check Version
Any Platform
# Check mongosh version $ mongosh --version
2.1.1
# Get help $ mongosh --help
$ mongosh [options] [db address] Options: -h, --help Show this help --version Show version information --shell Start shell --nodb Start shell without connecting to database ...
Connect to MongoDB

If you have MongoDB running locally, test the connection:

MongoDB Shell
# Connect to local MongoDB $ mongosh
Current Mongosh Log ID: 657b3a4c9e8a7b2c3d4e5f6a Connecting to: mongodb://127.0.0.1:27017 Using MongoDB: 7.0.5 Using Mongosh: 2.1.1 For mongosh info see: https://docs.mongodb.com/mongodb-shell/ test>
# Try a simple command test> db.version()
7.0.5
# Exit shell test> exit
✅ Success! mongosh is installed correctly and can connect to MongoDB.
📚

Basic Usage

Essential mongosh commands

Connection Strings
Connection Examples
# Connect to localhost (default) $ mongosh # Connect to specific host and port $ mongosh "mongodb://192.168.1.100:27017" # Connect to specific database $ mongosh "mongodb://localhost:27017/mydb" # Connect with authentication $ mongosh "mongodb://username:password@localhost:27017" # Connect to MongoDB Atlas $ mongosh "mongodb+srv://cluster0.xxxxx.mongodb.net"
Common Commands
Inside mongosh
# Show all databases test> show dbs # Switch to a database test> use mydb # Show collections in current database mydb> show collections # Insert a document mydb> db.users.insertOne({ name: "Alice", age: 30 }) # Find documents mydb> db.users.find() # Get help mydb> help # Exit mydb> exit
JavaScript Features

mongosh supports modern JavaScript (ES6+):

JavaScript in mongosh
# Use arrow functions test> db.users.find().forEach(u => print(u.name)) # Use async/await test> const result = await db.users.findOne({ name: "Alice" }) # Use template literals test> const name = "Bob" test> db.users.insertOne({ greeting: `Hello, ${name}!` }) # Use destructuring test> const { name, age } = db.users.findOne()
🔧

Troubleshooting

Common issues and solutions

Command Not Found

Symptoms: mongosh: command not found

Windows Solution:

  1. Restart your terminal/PowerShell
  2. Check if mongosh is in PATH: where mongosh
  3. Reinstall using the MSI installer

macOS/Linux Solution:

  1. Check if installed: which mongosh
  2. Verify it's in /usr/local/bin
  3. Add to PATH if needed:
    $ echo 'export PATH="/usr/local/bin:$PATH"' >> ~/.zshrc $ source ~/.zshrc
Connection Refused

Symptoms: MongoServerError: connect ECONNREFUSED

Solutions:

  1. Make sure MongoDB server is running
  2. Check MongoDB is listening on port 27017
  3. Verify connection string is correct
  4. Check firewall settings
Permission Denied (macOS)

Symptoms: Permission denied when running mongosh

Solution:

$ sudo chmod +x /usr/local/bin/mongosh