mongosh

library2.8.2jsnpmunverified

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.

database

npm install mongosh

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · MONGOSH

mongosh

databasejavascriptv2.8.2

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

mongosh (main package)

✓ // Not designed for direct JavaScript import. Install globally via npm and run from terminal.

✗ import mongosh from 'mongosh'; const mongosh = require('mongosh');

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)

✓ // These objects are available within the mongosh REPL environment, not via Node.js imports. Use `mongodb` driver for Node.js applications.

✗ import { db, ObjectId } from 'mongosh'; const { BSON } = require('mongosh');

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)

✓ import { spawn } from 'child_process';

✗ import { executeMongosh } from 'mongosh'; // No such exported function

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.

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

Debug

Known issues

breakingStarting 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.

affects: >=2.6.0

deprecatedThe 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.

affects: >=2.7.0

gotchaThe `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.

affects: >=1.0.0

gotchaFor 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.

affects: >=1.0.0

Errors

Common errors & fixes

mongosh: command not found

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

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

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.

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.

Upgrade

Version history

2.8.2latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

7 hits · last 30 days

node

Amazon

Resources

githubhttps://github.com/mongodb-js/mongosh ↗

packagehttps://www.npmjs.com/package/mongosh ↗

homepagehttps://www.mongodb.com/products/mongosh ↗