dlib: a C++ machine learning toolkit with Python bindings

What dlib is for, and who ends up using it

dlib is a C++ toolkit containing machine learning algorithms and tools for building software in C++. The README states the goal plainly: solving real world problems in C++. That framing matters because it is not a Python-first research library with a C++ core bolted on for speed. The C++ side is the product, and the Python package in tools/python is a binding layer compiled against the same sources.

The people who get value from it fall into two groups. The first writes C++ services and needs algorithms that link into an existing binary without dragging in a Python runtime. The second writes Python and wants computer vision or classical ML without leaving the language, installing through pip. Both groups are served by the same repository, but they have very different build experiences, and that split is the single most useful thing to understand before starting.

The scope is wide. The examples directory covers Bayesian networks, assignment learning, compression streams, directory navigation, custom trainers, and a long list of deep learning programs including face recognition, ImageNet classification and instance segmentation. A toolkit that ships a bayes_net_ex.cpp next to dnn_face_recognition_ex.cpp is aiming at general-purpose use rather than one narrow task.

How the C++ library and the Python bindings relate

The architecture is a C++ library with a Python wrapper generated through CMake. The pyproject.toml declares a build system that requires setuptools, wheel, packaging and cmake, and uses setuptools.build_meta as the backend. There is no separate Python implementation of the algorithms. When you install the Python package, setup.py drives CMake over the bindings project in tools/python and copies the outputs into standard Python packages.

That design has a direct consequence: Python build options are CMake options in disguise. The setup.py docstring explains that build settings can be changed by passing parameters to setup.py or by setting DLIB_* environment variables. It gives a concrete example, setting DLIB_NO_GUI_SUPPORT to ON adds the cmake option -DDLIB_NO_GUI_SUPPORT=ON. The same docstring documents --no to disable a cmake option, --set to pass arbitrary cmake options, --compiler-flags to forward flags to the compiler, -G to pick a CMake generator, and --clean to delete previous build folders.

The --clean flag is worth noting because the docstring warns you should use it if you change build options with --compiler-flags or --no since the last build, so the changes take effect. That is a build-system detail, but it catches people who change a flag, rebuild, and see no difference.

Data flow inside a C++ program is conventional for a library of this kind: you construct objects such as trainers or networks, feed them data through the documented interfaces, and serialize results. The examples folder is the practical reference for the shape of that code, and the site at dlib.net carries the API reference.

Installing dlib and running a first program

For Python, the README gives two routes. The stable release comes from PyPI:

pip install dlib

After that, importing dlib in a Python session should succeed. The alternative is to build the latest version from source, which requires a working C++ toolchain and CMake because the package compiles the bindings:

git clone https://github.com/davisking/dlib.git
cd dlib
pip install .

The README notes that build settings can be passed through setup.py parameters or DLIB_* environment variables, with DLIB_NO_GUI_SUPPORT=ON mapping to -DDLIB_NO_GUI_SUPPORT=ON.

For C++, the README points at the examples folder. Building every example is three commands:

mkdir build; cd build; cmake .. ; cmake --build .

If your CPU supports AVX instructions, the README says turning them on makes some things run faster:

mkdir build; cd build; cmake .. -DUSE_AVX_INSTRUCTIONS=1; cmake --build .

Visual Studio users get an explicit warning in the README: the default is 32-bit, both for outputs and for Visual Studio's own execution, so you should tell it to use 64-bit. The README suggests a generator invocation such as cmake .. -G "Visual Studio 14 2015 Win64" -T host=x64. If you use vcpkg, the README gives a single command, vcpkg install dlib, which brings CMake integration with it. To link dlib into your own C++ program rather than the examples, the README points to examples/CMakeLists.txt as a tutorial and to the compile page on dlib.net.

Where dlib gets in your way

The build is the first limitation, and it is not incidental. The Python package is compiled from C++ sources at install time, so pip install dlib is not a pure download. On a machine without a C++ compiler, CMake, or the headers the build expects, that command fails, and the failure surfaces as a compiler error rather than a friendly message about a missing dependency. The README offers no prebuilt wheel path, so there is nothing to fall back on except fixing the toolchain.

AVX instructions are a second trap. The README presents -DUSE_AVX_INSTRUCTIONS=1 as a speed option, and it is opt-in. If you build a binary with AVX enabled and deploy it to older hardware that lacks those instructions, you have a portability problem that the README does not discuss. The same applies in reverse: leaving AVX off on a modern machine gives up performance the hardware could deliver. The documentation does not help you decide, so that decision is yours.

Windows users carry extra weight. The README spends a paragraph on the 32-bit default in Visual Studio, which means a naive build produces a 32-bit library and a 32-bit executable. If you are linking against 64-bit dependencies, that mismatch will not be obvious from the CMake output.

Finally, dlib is not a training platform. There is no mention of distributed training, experiment tracking, or a hosted model registry. The deep learning examples are self-contained programs. If your workflow depends on those surrounding services, dlib is the wrong layer of the stack.

dlib against OpenCV and against PyTorch

The closest comparison for the computer vision side is OpenCV, and the difference is in emphasis. OpenCV is built around image processing and vision primitives with a broad set of classical operators; dlib pairs a smaller vision surface with a general machine learning toolkit, including Bayesian networks, assignment learning and custom trainers, plus its own deep learning implementation. If your work is mostly image manipulation, OpenCV covers more ground. If you need a trainer and a face recognition model in the same C++ dependency, dlib's combination is the reason to pick it.

Against PyTorch the split is sharper. PyTorch is a tensor and autograd framework with a large ecosystem around training; dlib's deep learning examples are programs that train and run specific architectures, such as the DCGAN, Inception and face recognition examples. dlib does not present itself as a general autograd engine. Choosing dlib for research on novel architectures would mean working against its grain. Choosing it to embed a trained model into a C++ binary is exactly the use its README describes.

One more distinction: dlib is licensed under the Boost Software License. The README states the long and short of it, that you can use dlib however you like, even in closed source commercial software. That permissiveness is a real differentiator when the alternative is a copyleft vision stack, and it removes a class of legal review from the adoption path. It is not legal advice, and you should read LICENSE.txt yourself.

Maintenance, releases and the cost of upgrading

The repository is not archived, and the last push was on 2026-08-11. The most recent release listed is v20.0.1 from 2026-03-29, following v20.0 from 2025-05-28 and v19.24.9 from 2025-05-15. The release cadence is not fast. A major version bump to 20.0 landed in mid-2025, and the patch release came roughly ten months later.

That rhythm shapes the upgrade calculus. You are not chasing weekly changes, which is good for stability and bad if you are waiting on a specific fix. The bigger cost sits in the build. Because the Python package compiles the C++ bindings, an upgrade is a recompile, and a recompile can fail for reasons unrelated to dlib: a new compiler version, a changed CMake policy, a missing system header. The setup.py docstring's advice to use --clean when build options change is the practical mitigation, and it applies to upgrades as much as to flag changes.

On the C++ side, upgrades mean rebuilding your own project against the new headers. If you enabled AVX or other CMake options, keep those invocations in version control next to your build script, because the README treats them as command-line choices rather than defaults you can rely on.

Licensing is settled and stable. The Boost Software License permits use in closed source commercial software according to the README, and the full text lives in LICENSE.txt. There is no dual-licensing scheme described, no commercial tier, and no contributor agreement mentioned in the README. For a dependency you intend to ship, that is about as simple as it gets.

Editorial conclusion

Adopt dlib if you need a single dependency that covers classical ML, deep learning and computer vision from C++, or if you want the same algorithms reachable from Python through the tools/python bindings. Do not adopt it if you expect a managed training framework with a large model zoo, or if you cannot build C++ on your target machines. Before committing, verify that your compiler and CMake version satisfy the build, confirm whether you want AVX instructions enabled, and check the Boost Software License text in LICENSE.txt against your distribution requirements.

Frequently asked questions

Official sources

1. davisking/dlib on GitHub
2. License: BSL-1.0
3. Project website
4. README
5. Releases