Build MongoDB From Source

As you make changes, you will need to build the server and run the appropriate test suites.

Changed in version 3.0.0: As of MongoDB 3.0, you must build the tools separately from the server. The tools are now written in Go and have their own build process. See: Build MongoDB Tools From Source for build instructions.

Though the exact dependencies and semantics differ by operating system, building the server from source has the same basic steps.

Dependencies & Installation

To build MongoDB, you will need:

  • A modern C++ compiler. One of the following is required.
    • GCC 4.8.2 or newer
    • Clang 3.4 (or Apple XCode 5.1.1 Clang) or newer
    • Visual Studio 2013 Update 2 or newer
  • Python 2.7

  • SCons 2.3

MongoDB uses SCons to build the Server and the shell. While it is unnecessary to know all the intricacies of SCons, glancing over the documentation may be helpful. SCons is unlikely to come preinstalled on your system, so make sure to install it using your preferred package manager.

Other basic requirements, independent of system, are to install Git and a recent 2.7.x version of Python.

Compiler Requirements

Changed in version 3.0.0.

To build MongoDB you must use one of the following minimum compiler versions:

  • Windows: Virtual Studio 2013 (i.e. MSVC12) Update 2
  • Linux: GCC 4.8.2
  • OS X: Clang 3.4 of XCode 5

System Specific Requirements

Further requirements are system-dependent and for both SCons and running the tests:

  • On Linux, you will need to install a compiler gcc or clang, as well as glibc headers which are usually included in a package named glibc-devel.

    • On Debian and Ubuntu systems, you must install the libssl-dev package to compile with SSL support.
    • On Red Hat and CentOS systems, you must install the openssl-devel package to compile with SSL support.
  • On Mac OS X, you will need to install XCode, specifically the command line tools.

  • On Windows, you will need to install Visual Studio 2013 or later. When running on Windows machines, it is recommended to install either pywin32 or ActivePython if you wish to do parallel builds.

  • On FreeBSD, the included compiler (gcc or clang) should suffice, but you will need to install devel/libexecinfo from ports or via pkgng.

  • On OpenBSD 5.4 or later, you will need to install gcc from ports (lang/gcc) or by using pkg_add You will also need to install devel/libexecinfo.

    When you run SCons, you will also need to pass additional arguments to scons to use the compiler from ports instead of the system compiler, i.e. --cc=egcc --cxx=eg++.

Building With SCons

Building the server executables consists of passing SCons a target; for example, when we build the MongoDB database server executable:

scons mongod

On Windows, this will instead be scons mongod.exe.

Other executables you may need to build include mongos or mongo, depending on what you are working on. You can pass SCons multiple targets in a list if necessary:

scons mongod mongo mongos

Alternatively, you may build everything, which includes mongo, mongod, mongos, and all the C++ unit tests:

scons all

All of these commands should be run from the root of the MongoDB repository.


If you are building an older version of MongoDB with a newer compiler, such as MongoDB 2.6 with Clang 3.5 on Mac OS X 10.10, you may need to include the --disable-warnings-as-errors option to your SCons invocation, as in the following:

scons all --disable-warnings-as-errors

This ensures that novel warnings in newer compilers do not prevent you from building older versions of MongoDB.

While certain top level build artifacts (like mongod and mongos) get copied to the top of the source tree during a build, other files like the C++ unit tests are generated underneath a subdirectory called build. The build directory is created at the top level of the source tree the first time you build anything.

Building can take a while, depending on which targets you are building and the capabilities of your computer. Without getting into all the intricacies of SCons, here are some flags to get you started:

  • --help

    This options provides help on both the intrinsic and local options. Read this.

  • -j <N> This option controls the number of parallel jobs SCons will use. Depending on what the local hardware is, you probably want to set this from anything between 1 and 32. Keep in mind that this isn’t just compilation, but also linking. Having 32 concurrent linking jobs running can make your machine pretty sluggish. Find a number that works for you, such as the number of cpus. When running on Windows machines, it is recommended to install either pywin32 or ActivePython if you wish to do parallel builds.

  • --ssl

    This option builds MongoDB with SSL support.

The following table lists some SCons aliases that are helpful with testing:

Alias Effect
all Builds everything (core and all tests)
dbtest Builds the dbtest program.
lint Runs the code linter
msi Builds the Windows MSI installer.
core Builds mongod, mongos, and the mongo shell.
install Installs to the directory used with the --prefix option, or to /usr/local if no --prefix was specified.
smoke Runs the “dbtest” test.
smokeCppUnittests Runs all the C++ unit tests.
smokeJsCore Runs (some of!) the Javascript integration tests.

Other aliases related to testing exist. Our aliases fall into two categories: ones that simply build targets, and ones that build targets and then run programs, typically a test harness of some kind. These latter aliases have dependencies defined for them, such that all the build targets that are necessary for a certain test are up to date before running the test. The only difference between, for example, the ‘dbtest’ and the ‘smoke’ aliases is that the former builds all the dependencies for the program named dbtest, and the latter does all that same work and additionally runs the dbtest program.

Windows Specific Instructions

Install Git from http://git-scm.com. When you install git, choose Checkout Windows-style commit Unix-style line endings. This will set the git option core.autocrlf to true. To verify the setting after installation, run the following command.

git config --get core.autocrlf

SCons requires Python 2.7.x. On Windows, ActiveState Python Community Edition is recommended to support parallel builds. Install either the 64-bit (x64) or 32-bit (x86) version depending on the machine architecture.

To install SCons 2.3.4 with ActiveState Python Community Edition, download the zip distribution of SCons, not the self-extracting exe installer labelled Windows. You must use the zip file, because self-extracting installer cannot find the 64-bit install of ActiveState Python. Unpack the SCons zip file, and if Python is installed at the default path, use the following command:

c:\python27\python.exe setup.py install

MongoDB version 2.4.x supports VS 2010. MongoDB 2.6.x, and 2.7.x support VS 2010, VS 2012, and VS 2013. MongoDB version 3.0.x requires VS 2013.

Finally, to build MongoDB for Windows, you will need to specify whether SCons will target 32-bit or 64-bit. SCons will target 32-bit builds by default. For 64-bit builds, run the following command:

scons --64

For 32-bit builds, run the following command:

scons --32

Building with Visual Studio 2013 & Later

To build with SCons, first start a VS2013 x64 Native Tools Command Prompt, and within this command shell environment, run the SCons commands listed above.

In a typical Visual Studio installation, the batch file to set up the VS 2013 environment has the following path:

%ProgramFiles(x86)%\Microsoft Visual Studio 12.0\vc\bin\amd64\vcvars64.bat

It is also available in the Visual Studio Tools folder in the Start Menu.