Flashlight: a C++ tensor and autograd library you build from source

What Flashlight is for, and who it is for

Flashlight is a machine learning library written entirely in C++ and published under the MIT licence. The README describes it as coming from Facebook AI Research and the creators of Torch, TensorFlow, Eigen and Deep Speech. That lineage matters less than the positioning: the library is aimed at people who want to write model code in C++ and keep the ability to change what happens underneath.

The README lists three core features: total internal modifiability, including internal APIs for tensor computation; a small footprint, with the core clocking in at under 10 MB and 20k lines of C++; and high-performance defaults that use just-in-time kernel compilation through the ArrayFire tensor library. The stated emphasis is efficiency and scale.

The intended user is a researcher or systems engineer who wants to modify the tensor layer itself, not just call into it. That is a narrower audience than a general deep learning framework serves. If your work is training a standard architecture on a standard dataset, the small core and the internal APIs buy you very little. If your work involves a custom kernel, a new memory layout, or an unusual training loop where the framework's defaults get in the way, the same properties are the reason to look at this repository at all.

How the pieces fit: lib, fl, pkg, app

The repository is split into four directories, and the README describes each. flashlight/lib holds kernels and standalone utilities, with audio processing given as an example. flashlight/fl is the core tensor interface and neural network library, and it uses ArrayFire by default. flashlight/pkg contains domain packages for speech, vision and text built on the core. flashlight/app contains applications of the core library across domains.

That layering is the architecture. The tensor interface sits at the bottom, the neural network abstractions wrap it, the domain packages add task-specific code, and the apps are complete training programs. The README points to four apps in a single repository: automatic speech recognition, formerly the wav2letter project, image classification, object detection, and language modeling.

Two mechanisms are worth separating. Tensors come from ArrayFire, which the README says provides just-in-time kernel compilation. Autograd is separate: Variable is described as a tape-based abstraction that wraps Flashlight tensors. The README's autograd example builds A as a Variable with a calcGrad flag set to true, then computes B as 2.0 * A, C as 1.0 + B, and D as log(C). Calling D.backward() populates A.grad() along with gradients for B, C and D. That is a define-by-run tape, and the README states plainly that it works as you would expect.

The neural network layer is module-based. Sequential forms a sequence of Module objects for chaining computation, and the README's convnet example adds View, Conv2D, ReLU, Pool2D, Linear, Dropout and LogSoftmax layers in order. Forward and backward are then two calls: model.forward(input), then loss.backward() on the result of categoricalCrossEntropy. Nothing here is unusual, and that is the point. The API surface is close to what a PyTorch user would recognise, expressed in C++.

Getting it running: vcpkg, Docker, or source

The README lists five installation routes: vcpkg, Docker, from source, from source with vcpkg, and building your own project against Flashlight. The minimum requirements it states are a C++ compiler with good C++17 support such as gcc or g++ version 7 or later, CMake version 3.10 or later plus make, and a Linux-based operating system. There is no Windows or macOS path in the requirements section.

For vcpkg, the README's badges point at two ports, flashlight-cuda and flashlight-cpu, with the install commands rendered as vcpkg install flashlight-cuda and vcpkg install flashlight-cpu. Docker images are published under the flml/flashlight namespace with cuda-latest and cpu-latest tags. The README also notes that instructions for building and installing Python bindings live in bindings/python/README.md, so Python is available as a binding rather than as the primary interface.

Once installed, linking is a normal CMake affair, and the include in the README's example is a single header: #include <flashlight/fl/flashlight.h>. The MNIST tutorial is referenced as the full walkthrough covering a training loop and dataset abstractions. If you only read one page before deciding, read that one, because the README's convnet snippet stops at model definition and does not show how data is fed or how the optimiser is stepped.

The release cadence is the first thing to check

The most recent tagged release listed is v0.3.2, dated 2022-03-19. Before that, v0.3.1 on 2021-10-15 and v0.3 on 2021-04-16. The repository is not archived and the last push recorded is 2026-06-22, so the main branch is active while the tags are not. That gap between tag dates and commit activity is the single most important fact for anyone evaluating this for production use.

What it means in practice: if you pin to v0.3.2, you are pinning to a snapshot from 2022 and you should expect the main branch to have moved on in ways the release notes do not describe. If you track main, you are depending on an untagged state. Neither is automatically wrong, but the two choices have different support stories and you should pick deliberately rather than by accident. A vcpkg port may also pin its own revision, so the version you get from vcpkg install flashlight-cpu is not necessarily the version at the tip of main. Check the port's pinned revision before assuming they match.

The README's claim of a core under 10 MB and around 20k lines of C++ is a size statement, not a maturity statement. A small core is easier to read and to modify. It also means fewer layers of abstraction stand between your code and the ArrayFire calls, which is either the feature you want or an extra maintenance surface you now own.

Where it is the wrong tool

The requirements section is the clearest constraint: a Linux-based operating system, a C++17 compiler, CMake 3.10 or later. If your team works in Python and expects pip install to be the whole setup, Flashlight is the wrong layer to start from. The Python bindings exist, but the README treats them as a separate build with their own README, not as the default experience.

The second constraint is ArrayFire. Flashlight's default tensor backend is ArrayFire, and the README's performance story is tied to ArrayFire's just-in-time kernel compilation. That is a dependency you inherit, with its own build requirements and its own backend selection. The README does not promise that swapping in a different tensor implementation is a configuration flag, even though the tensor interface is described as modifiable. Modifiable in source is not the same as pluggable at runtime, and the README does not draw that distinction for you.

Third, the applications in flashlight/app are research applications. The README describes them as apps for research across multiple domains. Treating the ASR app as a supported product with a compatibility guarantee would be reading more into the repository than the README states. The same caution applies to the domain packages: they are built on the core, and their API stability is not described in the material available here.

How it differs from PyTorch and libtorch

The obvious comparison is libtorch, the C++ distribution of PyTorch, and the difference is architectural rather than syntactic. Both expose tensors, modules and tape-based autograd, and the README's Sequential, Conv2D and backward() calls will look familiar to anyone who has used the C++ frontend of PyTorch. The divergence is underneath.

Flashlight's tensor layer is ArrayFire, and the README's stated default is just-in-time kernel compilation through it. The core is described as under 10 MB and around 20k lines of C++, with internal APIs for tensor computation exposed. libtorch ships the ATen and dispatcher machinery that supports the full Python ecosystem, which is a much larger surface and a much larger build. If your goal is to modify how a tensor operation is compiled or dispatched, the smaller core with exposed internal APIs is the reason to choose Flashlight. If your goal is to reuse the operator coverage and the surrounding tooling that the Python ecosystem has accumulated, libtorch is the shorter path, and it is not close.

A second comparison is to writing CUDA kernels directly against a library like cuBLAS. That gives you total control and no framework at all. Flashlight sits between the two positions: it gives you a tensor abstraction and an autograd tape, and it still lets you reach into the tensor implementation. Whether that middle position is worth occupying depends on how much of the framework you intend to replace.

Maintenance cost and what the MIT licence leaves open

The maintenance picture has two parts. The first is the dependency chain: ArrayFire, CMake 3.10 or later, a C++17 compiler, and for GPU work a CUDA toolchain. Each of those moves independently of Flashlight, and the README's Docker images under flml/flashlight exist partly to spare you from assembling that chain yourself. If you build from source, you own the chain.

The second part is the tag gap described above. Pinning to v0.3.2 gives you a fixed target, but the main branch is where recent work appears to be, and the release notes for anything after v0.3.2 are not in the material available here. Upgrading from a pinned tag to main is therefore an exercise you should scope before you start, not after.

On licensing: the repository is MIT, which is permissive and places few conditions on redistribution. That is the whole of what can be said from the repository metadata. What MIT means for your specific product, your distribution model, or your organisation's policy is a question for your own legal review, and this article is not legal advice. The README's badges also reference a Gitter community chat, which is the communication channel it advertises.

Editorial conclusion

Adopt Flashlight if you are writing C++17 on Linux and want a small, internally modifiable tensor and autograd core with domain packages rather than a Python-first stack. Do not adopt it if you need a stable tagged release with fast-moving upstream support, or if your team is not prepared to build ArrayFire and match its compiler and CUDA toolchain. Before committing, verify cmake --version reports 3.10 or later, confirm your compiler handles C++17, and check whether the vcpkg port flashlight-cuda or flashlight-cpu pins a revision that matches the main branch you intend to use.

Official sources

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