{"id":17037,"library":"mongosh","title":"MongoDB Shell (mongosh)","description":"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.","status":"active","version":"2.8.2","language":"javascript","source_language":"en","source_url":"https://github.com/mongodb-js/mongosh","tags":["javascript","mongosh","mongodb","mongo","shell"],"install":[{"cmd":"npm install mongosh","lang":"bash","label":"npm"},{"cmd":"yarn add mongosh","lang":"bash","label":"yarn"},{"cmd":"pnpm add mongosh","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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.","wrong":"import mongosh from 'mongosh';\nconst mongosh = require('mongosh');","symbol":"mongosh (main package)","correct":"// Not designed for direct JavaScript import. Install globally via npm and run from terminal."},{"note":"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.","wrong":"import { db, ObjectId } from 'mongosh';\nconst { BSON } = require('mongosh');","symbol":"db, ObjectId, BSON (MongoDB shell API objects)","correct":"// These objects are available within the mongosh REPL environment, not via Node.js imports. Use `mongodb` driver for Node.js applications."},{"note":"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.","wrong":"import { executeMongosh } from 'mongosh'; // No such exported function","symbol":"spawn (for programmatic CLI execution)","correct":"import { spawn } from 'child_process';"}],"quickstart":{"code":"// This quickstart demonstrates using the mongosh CLI, not programmatic Node.js imports.\n// First, ensure mongosh is installed globally via npm:\n// npm install -g mongosh\n\n// From your terminal, connect to a local MongoDB instance and insert a document:\nmongosh \"mongodb://localhost:27017/testdb\" \\\n  --eval \"db.collection('mycollection').insertOne({ item: 'notebook', qty: 50, tags: ['stationery', 'office'] })\"\n\n// Then, query the inserted document using --json for structured output:\nmongosh \"mongodb://localhost:27017/testdb\" \\\n  --eval \"db.collection('mycollection').find({ item: 'notebook' }).toArray()\" \\\n  --json=relaxed\n\n// For scripting, you can place shell commands into a JavaScript file (e.g., my_script.js):\n// // my_script.js\n// const conn = new Mongo('mongodb://localhost:27017/anotherdb');\n// const db = conn.getDB('anotherdb');\n// db.collection('documents').insertOne({ date: new Date(), message: 'Hello from mongosh script!' });\n// printjson(db.collection('documents').findOne());\n\n// And execute it via the CLI:\n// mongosh my_script.js","lang":"javascript","description":"Demonstrates global installation, connection to MongoDB, inserting and querying data using the `mongosh` CLI, and executing a JavaScript file containing shell commands."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=2.6.0"},{"fix":"Refer to the official MongoDB documentation for the `explain` command to update usage to the currently recommended syntax and methods.","message":"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.","severity":"deprecated","affected_versions":">=2.7.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"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.","cause":"The `mongosh` package was either not installed globally, or the npm global bin directory is not in your system's PATH.","error":"mongosh: command not found"},{"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.","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.","error":"Error: command not found: db"},{"fix":"Verify your `--username`, `--password`, `--authenticationDatabase`, and `--authenticationMechanism` options. Ensure the user has the necessary permissions on the specified database.","cause":"Incorrect username, password, authentication database, or authentication mechanism provided when connecting to a MongoDB instance that requires authentication.","error":"Failed to connect to <address> authentication failed"},{"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.","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.","error":"Error: Node.js version <X> is not supported by mongosh."}],"ecosystem":"npm","meta_description":null}