Docs4dev
Docs
mongodb / v3.6 / reference / tutorial-install-mongodb-on-os-x.html

Install MongoDB Community Edition on macOS

On this page

Overview

Use this tutorial to install MongoDB 3.6 Community Edition on macOS using the third-party brew package manager.

MongoDB Version

This tutorial installs MongoDB 3.6 Community Edition. To install a different version of MongoDB Community, use the version drop-down menu in the upper-left corner of this page to select the documentation for that version.

Considerations

Platform Support

MongoDB 3.6 Community Edition supports macOS 10.10 or later.

Note

MongoDB 3.6 is not tested on APFS, the new filesystem in macOS 10.13 and may encounter errors.

See Supported Platforms for more information.

Production Notes

Before deploying MongoDB in a production environment, consider the Production Notes document which offers performance considerations and configuration recommendations for production MongoDB deployments.

Install MongoDB Community Edition

Prerequisites

If you have the Homebrew brew package installed on your OSX host and you have previously tapped the official MongoDB Homebrew Tap , skip the prerequisites and go to the Procedure step.

Install XCode

Apple’s XCode includes command-line tools that are required by brew, and is available for free on the App Store. Make sure you are running the latest version.

Install Homebrew

OSX does not include the Homebrew brew package by default. Install brew using the official instructions .

Tap the MongoDB Homebrew Tap

Issue the following from the terminal to tap the official MongoDB Homebrew Tap :

brew tap mongodb/brew

Procedure

Follow these steps to install MongoDB Community Edition using the third-party brew package manager.

From a terminal, issue the following:

brew install mongodb-community@3.6

Tip

If you have previously installed an older version of the formula, you may encounter a ChecksumMismatchError. To resolve, see Troubleshooting ChecksumMismatchError.

In addition to the binaries, the install creates:

Run MongoDB Community Edition

Follow these steps to run MongoDB Community Edition. These instructions assume that you are using the default settings.

You can run MongoDB as a macOS service using brew, or you can run MongoDB manually as a background process. It is recommended to run MongoDB as a macOS service, as doing so sets the correct system ulimit values automatically (see ulimit settings for more information).

  • To run MongoDB (i.e. the mongod process) as a macOS service, issue the following:

    brew services start mongodb-community@3.6

    To stop a mongod running as a macOS service, use the following command as needed:

    brew services stop mongodb-community@3.6

  • To run MongoDB (i.e. the mongod process) manually as a background process, issue the following:

    mongod --config /usr/local/etc/mongod.conf --fork

    To stop a mongod running as a background process, connect to the mongod from the mongo shell, and issue the shutdown command as needed.

Both methods use the /usr/local/etc/mongod.conf file created during the install. You can add your own MongoDB configuration options to this file as well.

macOS Prevents mongod From Opening

macOS may prevent mongod from running after installation. If you receive a security error when starting mongod indicating that the developer could not be identified or verified, do the following to grant mongod access to run:

  • Open System Preferences
  • Select the Security and Privacy pane.
  • Under the General tab, click the button to the right of the message about mongod, labelled either Open Anyway or Allow Anyway depending on your version of macOS.

To verify that MongoDB is running, search for mongod in your running processes:

ps aux | grep -v grep | grep mongod

You can also view the log file to see the current status of your mongod process: /usr/local/var/log/mongodb/mongo.log.

Connect and Use MongoDB

To begin using MongoDB, connect a mongo shell to the running instance. From a new terminal, issue the following:

mongo

macOS Prevents mongo From Opening

macOS may prevent mongo from running after installation. If you receive a security error when starting mongo indicating that the developer could not be identified or verified, do the following to grant mongo access to run:

  • Open System Preferences
  • Select the Security and Privacy pane.
  • Under the General tab, click the button to the right of the message about mongo, labelled either Open Anyway or Allow Anyway depending on your version of macOS.

For information on CRUD (Create,Read,Update,Delete) operations, see:

Additional Information

Localhost Binding by Default

By default, MongoDB launches with bindIp set to 127.0.0.1, which binds to the localhost network interface. This means that the mongod can only accept connections from clients that are running on the same machine. Remote clients will not be able to connect to the mongod, and the mongod will not be able to initialize a replica set unless this value is set to a valid network interface.

This value can be configured either:

  • in the MongoDB configuration file with bindIp, or
  • via the command-line argument --bind_ip

Warning

Before binding to a non-localhost (e.g. publicly accessible) IP address, ensure you have secured your cluster from unauthorized access. For a complete list of security recommendations, see Security Checklist. At minimum, consider enabling authentication and hardening network infrastructure.

For more information on configuring bindIp, see MongoDB Configuration Hardening.

Troubleshooting ChecksumMismatchError

If you have previously installed an older version of the formula, you may encounter a ChecksumMismatchError resembling the following:

Error: An exception occurred within a child process:

  ChecksumMismatchError: SHA256 mismatch

Expected: c7214ee7bda3cf9566e8776a8978706d9827c1b09017e17b66a5a4e0c0731e1f

  Actual: 6aa2e0c348e8abeec7931dced1f85d4bb161ef209c6af317fe530ea11bbac8f0

 Archive: /Users/kay/Library/Caches/Homebrew/downloads/a6696157a9852f392ec6323b4bb697b86312f0c345d390111bd51bb1cbd7e219--mongodb-macos-x86_64-4.2.0.tgz

To retry an incomplete download, remove the file above.

To fix:

  1. Remove the downloaded .tgz archive.

  2. Retap the formula.

    brew untap mongodb/brew && brew tap mongodb/brew

  3. Retry the install.

    brew install mongodb-community@3.6