mlpack: A Header-Only C++ Machine Learning Library with Python, R, and Julia Bindings

What Problem mlpack Solves and Who Uses It

mlpack targets two audiences that other popular ML libraries underserve. The first is C++ engineers deploying ML models in resource-constrained environments such as embedded systems, robotics, or latency-sensitive servers where a Python runtime is impractical. The second is ML researchers who want to implement and benchmark new algorithms directly in C++ and compare against reference implementations.

The README describes the design goal as a machine learning analog to LAPACK: a low-level, efficient implementation of a wide array of ML methods. The library is header-only, meaning no separate compilation step is needed beyond installing the headers and linking against Armadillo. Python, R, Julia, and Go bindings, as well as command-line programs, are generated from the same underlying C++ implementations.

Dependencies and Architecture

mlpack requires a C++17 compiler, Armadillo >= 10.8, ensmallen >= 2.10.0, and cereal >= 1.1.2. Armadillo provides the dense and sparse matrix types that mlpack uses for all data representation. ensmallen provides the optimization routines. cereal handles serialization of models to disk.

The library bundles three header-only support libraries: STB for image loading, httplib for dataset download, and dr_libs for audio loading. If your project already uses system-provided versions of these, the build documentation covers compile-time definitions to prefer the system versions over the bundled ones.

If you compile Armadillo by hand, the README warns that LAPACK and BLAS must be enabled. The library is fiscally sponsored by NumFOCUS and uses an open governance model documented in `GOVERNANCE.md`.

Installing mlpack and Compiling a C++ Program

Detailed installation instructions are in `doc/user/install.md`. Once headers are installed with `make install`, using mlpack in a C++ application requires a single include:

#include <mlpack.hpp>

To compile with GCC, linking against Armadillo and enabling OpenMP:

g++ -O3 -std=c++17 -o my_program my_program.cpp -larmadillo -fopenmp

For neural network serialization, add the define before the include:

#define MLPACK_ENABLE_ANN_SERIALIZATION
#include <mlpack.hpp>

Without that define, any code that serializes a neural network produces a compilation error rather than a runtime failure, which surfaces the issue early. If you need to serialize networks using single-precision floats, define `MLPACK_ENABLE_ANN_SERIALIZATION_FMAT` instead.

The README notes a concrete performance hazard: OpenBLAS versions 0.3.26 and older compiled to use pthreads may use too many threads, causing significant slowdown. OpenBLAS builds compiled with OpenMP do not have this problem. The installation documentation covers workarounds.

Compile-Time Cost and How to Manage It

mlpack is a template-heavy library, and naive use of `#include <mlpack.hpp>` in large projects can produce very long build times. The README documents two practical mitigation strategies.

First, include only the headers you need. If your code uses only decision trees, include `<mlpack/methods/decision_tree.hpp>` instead of the full library header. This reduces the amount the compiler must instantiate.

Second, only define `MLPACK_ENABLE_ANN_SERIALIZATION` in translation units that actually serialize neural networks. The define triggers additional template instantiations; enabling it project-wide when it is only needed in one file unnecessarily inflates compile times for the rest of the project.

These are concrete decisions that affect build latency in production codebases, and they represent a real ongoing cost that teams should account for when evaluating mlpack against alternatives that use shared libraries instead of header-only templates.

Language Bindings and Command-Line Programs

Beyond the C++ interface, mlpack provides bindings for Python, R, Julia, and Go, plus standalone command-line programs. The Python bindings allow interactive prototyping in notebooks, and the README links to a Python quickstart at `doc/quickstart/python.md`. Similarly, R users have `doc/quickstart/r.md`, Julia users `doc/quickstart/julia.md`, and Go users `doc/quickstart/go.md`.

All bindings wrap the same C++ implementations, so a model trained via the command-line interface can be serialized with cereal and then loaded from a Python or C++ program. This interoperability is practical for workflows where training runs from a CLI script and inference is embedded in a C++ service.

The latest stable version at the time of the most recent release is 4.8.0, released on 2026-06-09.

mlpack vs PyTorch and scikit-learn

PyTorch is a deep learning framework that stores models as Python objects and executes operations through a C++ backend. It provides autograd, a large ecosystem of pretrained models, and tooling for distributed training. mlpack does not have autograd and its neural network support is narrower. For teams building transformers, diffusion models, or fine-tuning large pretrained checkpoints, PyTorch is the more suitable tool.

scikit-learn is the dominant Python library for classical ML tasks such as classification, regression, clustering, and model selection. Its API is simpler to use interactively and it integrates well with pandas and NumPy. mlpack covers many of the same algorithms but in C++, which is an advantage when you need a compiled, dependency-minimal binary rather than a Python environment.

dlib is a C++ ML library with a similar target audience to mlpack. The main architectural difference is that dlib compiles to a shared or static library, while mlpack is header-only. Teams that prefer to keep compile times low and distribute a prebuilt library may prefer dlib for that reason alone.

The critical distinction for deployment-focused teams is runtime dependency size. A Python application that uses scikit-learn or PyTorch carries the Python interpreter, NumPy, and often CUDA libraries as runtime dependencies. A C++ application using mlpack can be compiled to a static binary with Armadillo and BLAS as its only runtime dependencies. This matters for resource-constrained systems, microcontrollers, or airgapped environments where installing a Python stack is impractical. The header-only design reinforces this: once headers are installed, an application can be compiled and deployed with no mlpack dynamic library to manage.

Building the Test Suite and Verifying Installation

mlpack includes a test suite built with CMake. The README points to `doc/user/install.md#build-tests` for full test build instructions. Tests validate that the algorithms produce correct outputs and can catch configuration issues such as the OpenBLAS threading problem before they affect production code.

The repository layout separates headers under `src/`, CMake integration under `CMake/`, documentation under `doc/`, and distribution packaging under `dist/`. The `UPDATING.txt` file tracks backward-incompatible changes between releases, which is important context for teams upgrading from an older version. The `HISTORY.md` file provides a full change history.

The examples repository at https://github.com/mlpack/examples is separate from the main repository and provides complete application examples with Makefiles. These are useful as starting templates for new projects that use mlpack as a dependency.

Maintenance Status and License

The repository is not archived and its last push was on 2026-09-17. The license is listed as NOASSERTION in the repository metadata, but the repository root contains a `LICENSE.txt` and a `COPYRIGHT.txt`. The documentation and source files reference the BSD 3-Clause license. The project follows an open governance model and is sponsored by NumFOCUS.

The project accepts research citations in academic papers. The README provides a BibTeX entry for the 2023 Journal of Open Source Software paper describing mlpack 4. The most recent release is 4.8.0, published on 2026-06-09. The two prior releases were 4.7.0 (2026-02-01) and 4.6.2 (2025-05-22), indicating a release cadence of roughly one to four months between versions.

Editorial conclusion

mlpack is the right choice for C++ engineers who need ML algorithms in a production binary or an embedded system where Python is unavailable, and for researchers who want to prototype in C++ notebooks or run experiments via command-line programs. It is a poor fit for teams whose primary language is Python and who need the deep learning ecosystem around PyTorch or TensorFlow: mlpack provides neural network support but its strength is classical ML and deployment efficiency. Before adopting it, check that your BLAS/LAPACK stack is compatible: OpenBLAS versions 0.3.26 and older compiled with pthreads have a documented multi-threading issue that can cause significant slowdown, and switching to an OpenMP-compiled OpenBLAS build resolves it.

Frequently asked questions

Official sources

1. Issues
2. mlpack/mlpack on GitHub
3. Project website
4. README
5. Releases