Flashlight: a C++ machine learning library you link into your own build

The problem Flashlight targets: ML inside a C++ binary

Most machine learning frameworks assume you will drive training from Python and call into compiled kernels underneath. Flashlight inverts that. It is a standalone C++ library, and the README describes it as written entirely in C++, with the core clocking in at under 10 MB and roughly 20k lines of C++. The stated audience is research and engineering work where the surrounding system is already C++ and adding a Python interpreter is unwelcome.

The project is explicit about its priorities: total internal modifiability, a small footprint, and high-performance defaults. The tensor layer is exposed through internal APIs, so you are not confined to a fixed operator set. Domain packages for speech, vision and text sit on top of the core, and the repository also carries applications for automatic speech recognition, image classification, object detection and language modeling.

The layout reflects that split. flashlight/lib holds kernels and standalone utilities such as audio processing. flashlight/fl is the core tensor interface and neural network library. flashlight/pkg contains the domain packages, and flashlight/app contains the end applications. If you only need dense tensor math, you can take the core and ignore the rest.

The trade-off is opinionation. Flashlight does not try to be a batteries-included training framework with a model zoo. The README frames it as enabling fast iteration on new experimental setups with little unopinionation. That is a real design stance, and it means you supply more of the scaffolding yourself.

How Flashlight works: ArrayFire tensors, a tape, and Sequential modules

At the bottom, Flashlight uses the ArrayFire tensor library by default, and the README ties its performance defaults to just-in-time kernel compilation with modern C++. The tensor type is defined in flashlight/fl/tensor/TensorBase.h, and the README points to internal APIs for tensor computation as a core feature.

Automatic differentiation is tape-based. The Variable abstraction wraps a Flashlight tensor, and gradients are recorded as you build the expression graph. The README's own example constructs a Variable with calcGrad set to true, multiplies and adds and takes a log, then calls backward, which the README says populates the gradient on the input along with gradients for the intermediate nodes.

On top of that sits the Module abstraction. Sequential chains modules in order, and the README's convnet example shows the pattern: a View to reshape the input, Conv2D layers with explicit input channels, output channels and kernel dimensions, ReLU and Pool2D, then Linear layers, Dropout and LogSoftmax. Forward and backward are two calls, with categoricalCrossEntropy as the loss.

The important architectural point is where state lives. Because the tensor API is exposed and the autograd tape is a thin wrapper, you can drop below the module layer when an experiment needs a kernel the library does not ship. That is the flexibility the README advertises, and it is also why the library stays small.

Installing Flashlight with vcpkg and running a first convnet

The README lists three installation routes: vcpkg, Docker, and building from source. It also links a from-source build with vcpkg and a page on building your own project against Flashlight. The minimum compilation requirements it states are a C++ compiler with good C++17 support such as gcc/g++ 7 or later, CMake 3.10 or later with make, and a Linux-based operating system.

The vcpkg badges in the README point at two separate ports, one for the CUDA backend and one for the CPU backend. The badge text encodes the install command, so the CPU path is:

vcpkg install flashlight-cpu

and the CUDA path is the same command with the other port name:

vcpkg install flashlight-cuda

After that, link Flashlight into your own CMake project. The README does not reproduce the CMake snippet in the section we have, so follow the building your own project page linked from the Quickstart rather than guessing at target names.

Once linked, the smallest useful program is a model definition. The README's convnet example builds a Sequential model and adds layers with explicit arguments:

#include <flashlight/fl/flashlight.h>

Sequential model;
model.add(View(fl::Shape({IM_DIM, IM_DIM, 1, -1})));
model.add(Conv2D(1, 32, 5, 5, 1, 1, PaddingMode::SAME, PaddingMode::SAME));
model.add(ReLU());
model.add(Pool2D(2, 2, 2, 2));
model.add(View(fl::Shape({7 * 7 * 64, -1})));
model.add(Linear(7 * 7 * 64, 1024));
model.add(LogSoftmax());

The forward and backward calls are the part to check first, because they show what the API expects:

auto output = model.forward(input);
auto loss = categoricalCrossEntropy(output, target);
loss.backward();

What you should see is a gradient populated on the parameters registered with the model. The README points to a full MNIST tutorial covering the training loop and dataset abstractions, which is the right next step rather than assembling a loop from the Quickstart alone.

Where Flashlight is the wrong tool

The first limitation is platform. The requirements section states a Linux-based operating system at minimum. If your team builds on Windows, Flashlight is not the path of least resistance, and the README does not present a supported Windows workflow.

The second is release cadence. The most recent tagged release in the repository is v0.3.2 from 2022-03-19, following v0.3.1 in 2021 and v0.3 in 2021. The repository itself is not archived, and the last push was on 2026-06-22, so work is happening on main. But if your dependency policy pins to tagged versions, you are pinning to a release line that has not been cut in years, and you should decide whether tracking main is acceptable before you start.

The third is ecosystem. Flashlight is not a model hub. There is no equivalent of a large pretrained checkpoint library described in the README. The applications in flashlight/app are research applications, and the speech recognition app is described as formerly the wav2letter project. If your task is fine-tuning a pretrained transformer, a Python framework with a checkpoint ecosystem will get you there faster.

Finally, build cost is real. C++17, CMake, ArrayFire, and a choice between CPU and CUDA ports is a heavier setup than a pip install. For a one-off experiment, that cost is hard to justify.

Flashlight compared with LibTorch and a Python-first stack

The closest alternative in approach is LibTorch, the C++ distribution of PyTorch. The difference is architectural. LibTorch exposes the same operator set and serialization format as PyTorch, so a model trained in Python can be loaded and run from C++. Flashlight does not position itself that way. Its tensor layer is its own API over ArrayFire, its autograd is a tape built around Variable, and the README emphasizes internal modifiability rather than interchange with a Python ecosystem.

That produces a different decision. Choose LibTorch when the model already exists in Python and C++ is only the serving target. Choose Flashlight when the research or the algorithm itself is being written in C++, and you want to reach into the tensor implementation without leaving the language.

The second comparison is against staying in Python entirely. A Python stack gives you a wider set of libraries and faster iteration on data loading and experiment tracking. Flashlight's counterargument, as the README puts it, is a small footprint and no need to embed an interpreter. If your deployment target is a native binary with tight size constraints, the sub-10 MB core figure is the relevant number.

One caveat on both comparisons: the README does not describe an ONNX import path or a checkpoint interchange format, so treat model portability as something to verify in the source rather than assume.

Maintenance, licence and upgrade cost

The repository is not archived, and the last push was on 2026-06-22. That is recent activity on the default branch. It does not change the release picture: v0.3.2 from 2022-03-19 remains the newest tag in the list. Anyone who depends on tags should plan around a slow release cadence and decide whether pinning to main is acceptable.

Upgrade cost is dominated by the C++ surface. Because the README advertises internal tensor APIs as a feature, code that reaches below the module layer is more exposed to internal change than code that only composes Sequential modules. If you want cheap upgrades, stay on the public module and Variable interfaces.

The licence is MIT, as stated in the repository. MIT is permissive and permits use in proprietary software, but this is not legal advice and the obligations that matter to you depend on how you redistribute binaries and whether you modify the source. Read the LICENSE file in the repository root and get your own review.

One dependency note worth flagging: the default tensor backend is ArrayFire, which carries its own licence and build requirements. The README does not spell out the licensing relationship between the two in the section we have, so check it before shipping a product.

Editorial conclusion

Adopt Flashlight if your inference or training code already lives in C++ and you want autograd and tensor ops in the same binary, without a Python runtime in the loop. Do not adopt it if you need a large pretrained model zoo, a Python-first API, or Windows as a build target, because the requirements list a Linux-based operating system and the release history shows v0.3.2 from 2022-03-19 as the most recent tagged release. Before committing, verify that your CMake version is at least 3.10, that your compiler supports C++17, and whether the CPU or CUDA vcpkg port matches the hardware you intend to train on.

Frequently asked questions

Official sources

1. flashlight/flashlight on GitHub
2. License: MIT
3. Project website
4. README
5. Releases