dlib: a C++ toolkit where the build flags decide how fast your code runs
A toolkit for making real world machine learning and data analysis applications in C++
At a glance
- What is it?
- dlib is a long-running C++ machine learning and computer vision library with a Python binding layer built on top of it. The interesting decisions are not the algorithms but the build configuration, the licence, and the fact that it stays a C++ library with a Python wrapper bolted on rather than a Python-first project.
- Who is it for?
- Adopt dlib if your application is already C++ and you want machine learning and computer vision code that links into the same binary, or if you need a permissive licence that permits closed source commercial use. Do not adopt it if your team works primarily in Python and expects a pure-Python or GPU-first stack, because the Python API here is a binding layer over a C++ build and you inherit that build's constraints.
- Can I use it commercially?
- Yes. BSL-1.0 is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 36 days ago.
- What is it written in?
- Mainly C++, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The problem dlib solves is linking ML into a C++ program, not scripting it
Most machine learning libraries assume you will drive them from a scripting language. dlib assumes the opposite. The README opens by describing it as a C++ toolkit containing machine learning algorithms and tools for creating complex software in C++ to solve real world problems. That sentence sets the boundary. The intended user is someone writing a C++ application who needs classification, regression or computer vision inside the same process, without an interpreter hop and without a separate service. The repository topics list computer-vision, deep-learning and machine-learning alongside c-plus-plus and python, so both audiences exist, but the C++ side is the primary artifact and the Python side is described in the README as an API layered on top. If your work is a notebook or a Python service, the relevant question is not whether dlib has the algorithm you want, it is whether you can tolerate a compiled extension as the delivery mechanism. That is a different adoption decision from picking a pure Python package.
How the repository is laid out and how the two build paths diverge
The repository is a C++ library with a CMake build at its root and an examples directory that doubles as a tutorial. The README points at examples/CMakeLists.txt and calls it a CMake tutorial, which is a useful signal: the intended way to learn how to consume dlib in your own project is to read a CMakeLists file, not a prose guide. The Python path is separate. The README gives two routes, pip install dlib for the latest stable release from PyPI, or cloning the repository and running pip install . from the checkout. The second route is not a pure Python install. The README states that build settings can be changed by passing parameters to setup.py or by setting DLIB_* environment variables, and gives the example that setting DLIB_NO_GUI_SUPPORT to ON adds the cmake option -DDLIB_NO_GUI_SUPPORT=ON. So the Python install is a wrapper that invokes the same CMake machinery. That is the architectural fact worth internalising: there is one build system, and the Python package is a front end for it. Any flag that affects the C++ build affects the Python extension you end up with.
Getting it running: the exact commands from the README
For the C++ examples, the README gives a four step sequence from inside the examples folder: mkdir build; cd build; cmake .. ; cmake --build . That builds all the examples. To enable AVX, the README shows the same sequence with a flag inserted at configure time: cmake .. -DUSE_AVX_INSTRUCTIONS=1. The README says doing so will make some things run faster, and adds the conditional that this only applies if your CPU supports AVX instructions. That conditional matters more than the flag itself, because the flag is a compile time decision, and a binary compiled with AVX instructions is not portable to a machine without them. Visual Studio users get a separate instruction: build in 64 bit mode, using a generator string such as -G "Visual Studio 14 2015 Win64" with -T host=x64, because the default is 32 bit. There is also a vcpkg route, vcpkg install dlib, which the README says provides CMake integration in a single command. For Python, pip install dlib or a clone followed by pip install . The unit tests have their own documented sequence: cd dlib/test, mkdir build, cd build, cmake .., cmake --build . --config Release, then ./dtest --runall. The README notes that on Windows the compiler may place the test executable in a Release subfolder, in which case you have to change into it before running. The point of listing these is that none of them are optional detail. The configure step is where AVX, GUI support and 64 bit mode are decided, and each of those decisions is baked into the artifact.
AVX and 64 bit mode are the real portability trade-off
The most consequential thing in the README is a single flag. USE_AVX_INSTRUCTIONS is described as making some things run faster, with the precondition that your CPU supports AVX. That is a classic build-time performance decision with a distribution cost. If you compile with it and ship the binary, you have narrowed the set of machines that can run it. If you compile without it, you keep portability and give up whatever speedup the flag provides, which the README does not quantify. Notice what the README does not claim. It does not give a benchmark, it does not say how much faster, and it does not say which components benefit. Anyone who needs a number has to produce it themselves on their own workload. The same pattern applies to the Visual Studio note. The README is blunt that the default is 32 bit and that you probably want 64 bit, which is a build configuration decision that will silently affect addressable memory and the performance of anything memory bound. Both of these are the kind of thing that is easy to get wrong once and then inherit for the life of a project. The mitigation the README offers is not a compatibility matrix, it is the test suite: build dtest and run ./dtest --runall on the platform you actually care about.
The Boost Software License is the strongest argument for some teams
The README states the library is licensed under the Boost Software License, found in dlib/LICENSE.txt, and summarises it as: you can use dlib however you like, even in closed source commercial software. That is the practical content of BSL-1.0 and it is a genuine differentiator when you compare it against copyleft alternatives. It means the licence question does not force an architectural decision. You do not have to isolate dlib in a separate process, you do not have to publish modifications, and you do not have to route around it in a commercial product. The README itself frames the licence as a permission rather than a restriction, which is unusual and worth noting. What the README does not do is discuss attribution requirements or the exact wording of the licence text. It points at the file. If the licence is the reason you are choosing dlib, read LICENSE.txt rather than the summary sentence, because a one line characterisation is not the licence. Nothing here is legal advice, and the summary in a README is not a substitute for the text it points to.
Where the documentation is thin and what that costs you
The README is a build document, not an evaluation document. It tells you how to compile, how to install, how to run tests, and what the licence says. It does not tell you which algorithms are present, how they compare, what the accuracy characteristics are, or what the memory footprint looks like. For those, it defers entirely to http://dlib.net. That is a reasonable split for a mature project, but it means a reader of the repository alone cannot judge fitness. The README also carries a funding acknowledgement: work supported by the Office of the Director of National Intelligence, IARPA, under contract number 2014-14071600010, with the standard disclaimer that the views are those of the authors and do not represent official policies or endorsements. That is context about the project's history, not a statement about current development. The repository is not archived and the last push is dated 2026-08-11, with a v20.0.1 release on 2026-03-29 following v20.0 on 2025-05-28. A major version bump from 19.x to 20.x is the kind of event that warrants reading the release notes before upgrading, because the README gives no migration guidance at all.
When a C++-first toolkit is the wrong choice
The clearest failure mode is a Python team that wants a Python library. With dlib you get a compiled extension whose configuration is controlled by CMake options and DLIB_* environment variables. If your deployment target differs from your build machine, or if you rely on prebuilt wheels, you are one AVX flag away from a binary that will not start. Debugging that class of problem is not the same as debugging a pure Python dependency, and the README offers no guidance on wheel availability for specific platforms. A second case is a team that needs a GPU-first deep learning stack. The README lists deep-learning as a topic and describes dlib as containing machine learning algorithms, but it says nothing about accelerators, CUDA, or distributed training, and the only performance lever it documents is a CPU instruction set flag. If your workload is defined by large model training on GPUs, the documented surface of this project does not address it. A third case is a team that wants a small, auditable dependency. dlib is a broad toolkit, and the README's own framing is that it contains algorithms and tools for creating complex software. Breadth is the point, but breadth is also surface area you take on when you only need one classifier.
What a Python-first alternative would look like instead
The natural comparison is scikit-learn, and the difference is not a matter of quality but of where the boundary sits. scikit-learn is a Python package built on NumPy and SciPy, installed and consumed entirely within the Python ecosystem, with no CMake configure step in the user's path and no compile-time instruction set flag exposed as a documented knob. dlib inverts that: the C++ library is the product and the Python API is a binding, so the build configuration is part of your deployment surface. The trade is straightforward. If you need the algorithms callable from C++ in the same process, scikit-learn is not an option at all and dlib is. If you need a Python dependency that installs predictably across platforms without you managing compiler flags, scikit-learn's model is a better fit for that constraint. Neither is universally correct. The question to ask is whether your deployment story is a compiled artifact or an interpreted one, because that is the axis on which these two diverge, and the README of dlib makes the compiled-artifact assumption explicit from its first code block.
Editorial conclusion
Adopt dlib if your application is already C++ and you want machine learning and computer vision code that links into the same binary, or if you need a permissive licence that permits closed source commercial use. Do not adopt it if your team works primarily in Python and expects a pure-Python or GPU-first stack, because the Python API here is a binding layer over a C++ build and you inherit that build's constraints. Before committing, verify three things on your own machine: that the CMake configure step succeeds with your intended flags, that a build with USE_AVX_INSTRUCTIONS=1 actually runs on your target hardware rather than only on the machine that compiled it, and that your target platform can run the dtest suite to completion with ./dtest --runall. Those three checks tell you more about whether dlib fits than any feature list.
Community notes