Installing MongoDB on macOS with Homebrew: Migrating from Core Formula to Community Edition

Problem Background and Error Analysis

On macOS, Homebrew serves as a popular package manager, offering developers a convenient way to install software. However, when attempting to install MongoDB using the brew install mongodb command, many users encounter the following error message:

Error: No available formula with the name "mongodb" 
==> Searching for a previously deleted formula (in the last 
month)...
Warning: homebrew/core is shallow clone. To get complete history 
run:
  git -C "$(brew --repo homebrew/core)" fetch --unshallow

Error: No previously deleted formula found.
==> Searching for similarly named formulae...
Error: No similarly named formulae found.
==> Searching taps...
==> Searching taps on GitHub...
Error: No formulae found in taps.

This error indicates that the core formula for MongoDB has been removed from Homebrew's official repository (homebrew-core). According to public statements from the Homebrew core team, this removal was prompted by MongoDB's license change from an open-source to a non-open-source license. This shift triggered a reevaluation of software distribution compliance within the Homebrew community, ultimately leading to the formula's migration to a custom tap.

Solution: Using the MongoDB Community Edition Tap

To address the installation issue, the MongoDB team maintains a custom Homebrew tap that specifically provides support for installing the mongodb-community version. Below is the complete migration and installation procedure:

1. Stop and Uninstall Old Version: If an older version of MongoDB installed via the previous homebrew-core exists on the system, first stop the service and uninstall it. Execute the following commands:

   brew services stop mongodb
   brew uninstall homebrew/core/mongodb

   This step ensures a clean environment and prevents version conflicts.
2. Add MongoDB Custom Tap: Add the tap maintained by the MongoDB team using the brew tap command:

   brew tap mongodb/brew

   This command adds the mongodb/brew repository to the local Homebrew configuration, making the mongodb-community formula accessible.
3. Install mongodb-community: Install the MongoDB Community Edition from the newly added tap:

   brew install mongodb-community

   The installation process automatically handles dependencies and configures necessary system paths.
4. Start MongoDB Service: Use Homebrew's service management feature to start the database:

   brew services start mongodb-community

   This will run the MongoDB process in the background and set it to start automatically on boot.

After completing these steps, verify the installation by running mongod --version or test the connection using the mongo command.

Technical Principles and In-Depth Analysis

Homebrew's formula management system is based on Git repositories, with homebrew-core being the core formula library. When a formula is removed, Homebrew executes a multi-layered search logic: first checking for recently deleted formulas, then looking for similarly named formulas, and finally searching all taps on GitHub. The "shallow clone" hint in the error message indicates that the local repository might not have a complete history, affecting search efficiency.

The specific impact of MongoDB's license change lies in Homebrew's requirement, as an open-source project, to ensure that distributed software complies with its licensing policies. Non-open-source licenses may restrict redistribution or modification rights, prompting the Homebrew team to migrate the formula to a tap maintained directly by MongoDB. This approach both adheres to licensing requirements and provides ongoing installation support for users.

From a technical implementation perspective, custom taps store formula files in independent Git repositories, with a structure similar to homebrew-core. During installation, Homebrew downloads the formula from the specified tap, resolves dependencies, and performs compilation or binary installation. The mongodb-community formula may include optimized configurations for macOS systems, such as memory management or file path settings.

Best Practices and Considerations

During the migration and installation process, it is recommended to follow these best practices:

• Before performing any installation operations, run brew update to ensure Homebrew itself is up-to-date, avoiding issues due to outdated tools.
• If permission issues arise, use sudo or adjust file ownership, but exercise caution to prevent system security risks.
• After installation, use brew info mongodb-community to view formula details, including version information, dependencies, and configuration options.
• Regularly check MongoDB official documentation and Homebrew tap updates for security patches or new features.

Additionally, developers should note that the MongoDB Community Edition may differ in features from the old core formula. The community edition typically adheres to open-source protocols, providing basic database functionality, while enterprise features may require additional licenses. In project development, choose the appropriate version based on requirements.

Conclusion and Future Outlook

Through the detailed analysis in this article, we have resolved the error caused by formula removal when installing MongoDB on macOS via Homebrew. Key steps include: identifying the license change background, uninstalling old versions, adding a custom tap, and installing and starting mongodb-community. This process not only addresses specific technical issues but also deepens understanding of Homebrew's package management mechanisms and open-source software license compliance.

In the future, as the open-source ecosystem evolves, similar license changes may affect the installation methods of other software. Developers should stay informed about toolchain changes and adapt workflows flexibly. The custom tap model maintained by the MongoDB team offers a viable solution for such scenarios, ensuring continued accessibility of the software.

For further technical exploration, refer to MongoDB official documentation and Homebrew community discussions to stay updated on the latest developments and advanced configuration techniques.