MongoDB Shell (mongosh)

2.8.2 · active · verified Wed Apr 22

mongosh is the official command-line interface (CLI) for interacting with MongoDB deployments. It provides a modern JavaScript-based REPL (Read-Eval-Print Loop) for database administration, data manipulation, and development. The npm package `mongosh` acts as a convenience wrapper, primarily distributing the compiled `mongosh` binary rather than a JavaScript library for programmatic import. The current stable version is 2.8.2. New versions are released frequently, often coinciding with MongoDB server updates, Node.js runtime upgrades (e.g., moving to Node.js 24 in v2.7.0), and regular bug fixes and minor feature additions. It differentiates itself by being the officially supported, feature-rich, and actively maintained interactive shell for MongoDB, offering advanced features like schema sampling, streaming processor attributes, and improved authentication mechanisms compared to older MongoDB shells.

Common errors

```
mongosh: command not found
```
cause The `mongosh` package was either not installed globally, or the npm global bin directory is not in your system's PATH.

fix Ensure `mongosh` is installed globally with `npm install -g mongosh` and verify that your npm global bin path is correctly configured in your shell's PATH environment variable.
```
Error: command not found: db
```
cause This error occurs when attempting to use MongoDB shell commands (like `db.collection(...)`) in a standard Node.js environment or directly in your system's shell, outside of the `mongosh` REPL.

fix Run your MongoDB commands within the `mongosh` REPL after connecting to a database, or use the official `mongodb` driver for Node.js applications if you need programmatic interaction.
```
Failed to connect to <address> authentication failed
```
cause Incorrect username, password, authentication database, or authentication mechanism provided when connecting to a MongoDB instance that requires authentication.

fix Verify your `--username`, `--password`, `--authenticationDatabase`, and `--authenticationMechanism` options. Ensure the user has the necessary permissions on the specified database.
```
Error: Node.js version <X> is not supported by mongosh.
```
cause Although `mongosh` bundles its own Node.js runtime, the `npm install` process itself requires a compatible system Node.js version. If your system's Node.js is too old, the installation may fail.

fix Upgrade your system's Node.js version to meet the `mongosh` npm package's `engines` requirement (e.g., `>=16.15.0`). You can use a tool like `nvm` to manage Node.js versions.

Warnings

breaking Starting with v2.6.0, `mongosh` outputs full BSON objects by default for certain operations. This change might affect scripts or tools that parse `mongosh` output and rely on previous, potentially abbreviated, representations.
Fix: Update scripts that parse `mongosh` output to correctly handle full BSON object representations. Consider using the `--json=canonical` or `--json=relaxed` options for predictable JSON output formats.
deprecated The option-based `explain` API was deprecated in v2.7.0. While still functional for now, users should transition to the updated `explain` methods to ensure future compatibility and avoid potential breaking changes in later versions.
Fix: Refer to the official MongoDB documentation for the `explain` command to update usage to the currently recommended syntax and methods.
gotcha The `mongosh` npm package is a distribution wrapper for the `mongosh` CLI binary and bundles its own Node.js runtime (e.g., Node.js 24 since v2.7.0). Therefore, the system Node.js version is primarily relevant for the `npm install` process (requiring `>=16.15.0`), but not for the `mongosh` runtime itself. It is not intended for direct JavaScript `import` or `require` into Node.js applications.
Fix: Always use `mongosh` as a command-line tool. If programmatic interaction is required, use `child_process.spawn()` to execute the `mongosh` binary, understanding that this runs it as an external process.
gotcha For production environments or when requiring a fully supported `mongosh` binary with specific enterprise features or support, MongoDB recommends downloading `mongosh` directly from the official MongoDB website (https://www.mongodb.com/try/download/shell) rather than relying solely on the npm distribution. The npm package is primarily for ease of installation and development workflows.
Fix: For critical or supported deployments, obtain `mongosh` binaries directly from the official MongoDB download page to ensure access to all features and support channels.

Install

npm install mongosh npm
yarn add mongosh yarn
pnpm add mongosh pnpm

Imports

mongosh (main package)
wrong:
```
import mongosh from 'mongosh';
const mongosh = require('mongosh');
```
correct:
```
// Not designed for direct JavaScript import. Install globally via npm and run from terminal.
```
The `mongosh` npm package is a wrapper that provides the `mongosh` CLI binary. It does not export a default or named JavaScript API for direct `import` or `require`. Attempts to import it into a Node.js application will result in module resolution errors.
db, ObjectId, BSON (MongoDB shell API objects)
wrong:
```
import { db, ObjectId } from 'mongosh';
const { BSON } = require('mongosh');
```
correct:
```
// These objects are available within the mongosh REPL environment, not via Node.js imports. Use `mongodb` driver for Node.js applications.
```
Common MongoDB shell objects like `db`, `ObjectId`, and `BSON` are part of the `mongosh` REPL's execution context and are *not* exported from the `mongosh` npm package for use in external Node.js applications. To interact with MongoDB in Node.js, developers should use the official `mongodb` driver package.
spawn (for programmatic CLI execution)
wrong:
```
import { executeMongosh } from 'mongosh'; // No such exported function
```
correct:
```
import { spawn } from 'child_process';
```
To run `mongosh` commands programmatically from a Node.js script, use the `child_process` module to execute the `mongosh` binary as an external process. This is the intended method for programmatic interaction, rather than direct module imports.

Quickstart

Demonstrates global installation, connection to MongoDB, inserting and querying data using the `mongosh` CLI, and executing a JavaScript file containing shell commands.

// This quickstart demonstrates using the mongosh CLI, not programmatic Node.js imports.
// First, ensure mongosh is installed globally via npm:
// npm install -g mongosh

// From your terminal, connect to a local MongoDB instance and insert a document:
mongosh "mongodb://localhost:27017/testdb" \
  --eval "db.collection('mycollection').insertOne({ item: 'notebook', qty: 50, tags: ['stationery', 'office'] })"

// Then, query the inserted document using --json for structured output:
mongosh "mongodb://localhost:27017/testdb" \
  --eval "db.collection('mycollection').find({ item: 'notebook' }).toArray()" \
  --json=relaxed

// For scripting, you can place shell commands into a JavaScript file (e.g., my_script.js):
// // my_script.js
// const conn = new Mongo('mongodb://localhost:27017/anotherdb');
// const db = conn.getDB('anotherdb');
// db.collection('documents').insertOne({ date: new Date(), message: 'Hello from mongosh script!' });
// printjson(db.collection('documents').findOne());

// And execute it via the CLI:
// mongosh my_script.js

view raw JSON →