How to: Install libbson/libmongoc from Source#


This page assumes that you can successfully configure and build the components that you wish to install, which is detailed and explained on the Building the C Driver Libraries from Source tutorial page. Whereas that tutorial walks through getting the sources built and a minimal install working, this page will offer deeper guidance on the nuance and available options for installing the mongo-c-driver libraries from such a from-source build.

mongo-c-driver uses CMake to generate its installation rules, and installs a variety of artifacts of interest. For integration with downstream programs, the Config-file Packages and pkg-config files would be of particular interest.

If you are intending to import libbson or libmongoc via CMake or pkg-config, it can be helpful to be aware of how the respective tool searches for package metadata.

CMake builds a set of search paths based on a set of prefixes, which are read from both the environment and from configure-time CMake settings.

In particular, the $PATH environment variable will be used to construct the standard prefixes for the system. For each directory \(D\) in $PATH:

  1. If the final path component of \(D\) is “bin” or “sbin”, \(D\) is replaced with the parent path of \(D\).

  2. \(D\) is added as a search prefix.

This has the effect that common Unix-specific directories on $PATH, such as /usr/bin and /usr/local/bin will end up causing CMake to search in /usr and /usr/local is prefixes, respectively. If you have the directory $HOME/.local/bin on your $PATH, then the $HOME/.local directory will also be added to the search path. Having $HOME/.local/bin on $PATH is an increasingly common pattern for many Unix shells, and is recommended if you intend to do use a per-user-prefix for your installion.

Additionally, the CMAKE_PREFIX_PATH environment variable will be used to construct a list of paths. By default, this environment variable is not defined.

On Windows, the directories %ProgramW6432%, %ProgramFiles%, %ProgramFiles(x86)%, %SystemDrive%\Program Files, and %SystemDrive%\Program Files (x86) will also be added. (These come from the CMAKE_SYSTEM_PREFIX_PATH CMake variable, which is defined during CMake’s platform detection.)

See also

For detailed information on package lookup, refer to CMake’s Config Mode Search Procedure section for full details.

The pkg-config command-line tool looks for .pc files in various directories, by default relative to the path of the pkg-config tool itself. To get the list of directories that your pkg-config will search by default, use the following command:

Ask pkg-config what directories it will search by default#
$ pkg-config "pkg-config" --variable="pc_path"

Additional directories can be specified using the $PKG_CONFIG_PATH environment variable. Such paths will be searched before the default pkg-config paths.

On Windows, registry keys HKCU\Software\pkgconfig\PKG_CONFIG_PATH and HKLM\Software\pkgconfig\PKG_CONFIG_PATH can be used to specify additional search directories for pkg-config. Adding directories to the HKCU\… key is recommended for persisting user-specific search directories.

See also

If you have man and pkg-config installed on your system, lookup procedures are detailed in man 1 pkg-config. This documentation may also be found at many man page archives on the web, such as pkg-config at

Choosing a Prefix#

We will call the directory for the user-local installation $PREFIX. Selecting the path to this directory is somewhat arbitrary, but there are some recommendations to consider. The $PREFIX directory is the path that you will give to CMake or pkg-config when configuring a downstream project.

Selecting a System-Wide Installation Prefix#

If you wish to install the mongo-c-driver libraries in a directory that is visible to all users, there are a few standard options.

Using an install $PREFIX of /usr/local/ is the primary recommendation for all Unix platforms, but this may vary on some obscure systems.


DO NOT use /usr/ nor / (the root directory) as a prefix: These directories are designed to be carefully managed by the system. The /usr/local directory is intentionally reserved for the purpose of unmanaged software installation.

Alternatively, consider installing to a distinct directory that can be easily removed or relocated, such as /opt/mongo-c-driver/. This will be easily identifiable and not interact with other software on the system without explicitly opting-in.


It is strongly discouraged to manually install software system-wide on Windows. Prefer instead to use a per-user unprivileged installation prefix.

If you wish to perform a system-wide installation on Windows, prefer to use a named subdirectory of %ProgramData%, which does not require administrative privileges to read and write. (e.g. %ProgramData%\mongo-c-driver)

Installing with CMake#

After you have successfully configured and built the libraries and have selected a suitable $PREFIX, you can install the built results. Let the name $BUILD refer to the directory where you executed the build (this is the directory that contains CMakeCache.txt, among many other files).

From a command line, the installation into your chosen $PREFIX can be run via CMake using the cmake --install subcommand:

$ cmake --install "$BUILD" --prefix "$PREFIX"


If you configured the libraries while using a multi-config generator (e.g Visual Studio, Xcode), then you will also need to pass the --config command-line option, and must pass the value for the build configuration that you wish to install. For any chosen value of --config used for installation, you must also have previously executed a cmake --build within that directory with that same --config value.


If you chose to use a system-wide installation $PREFIX, it is possible that you will need to execute the installation as a privileged user. If you cannot run or do not want to run the installation as a privileged user, you should instead use a per-user installation prefix.


It is not necessary to set a CMAKE_INSTALL_PREFIX if you use the --prefix command-line option with cmake --install. The --prefix option will override whatever was specified by CMAKE_INSTALL_PREFIX when the project was configured.