xsimd: the example says AVX, the code says avx2, and the flag says -mavx
C++ wrappers for SIMD intrinsics and parallelized, optimized mathematical functions (SSE, AVX, AVX512, NEON, SVE, WebAssembly, VSX, RISC-V))
At a glance
- What is it?
- C++ wrappers that give batches of numbers the same arithmetic operators as single values, across ten instruction set families. The documentation contradicts itself in its first code sample, the vectorised loop quietly discards its tail, and version 8 is a full rewrite whose migration guide is still promised rather than written.
- Who is it for?
- xsimd suits a library author who wants one interface over batches of numbers instead of per-vendor intrinsics, and who can pin a compiler and a target instruction set in their own build. Before depending on it, check five things.
- Can I use it commercially?
- Yes. BSD-3-Clause 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 3 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 November 15, 2026, and from our analysis. They are not legal advice.
Star history
- xtensor-stack/xsimd2,777 ★ · +14
| Repository | 2026-10-04 | 2026-11-15 |
|---|---|---|
| xtensor-stack/xsimd | 2.8k | 2.8k |
14 Stars in the last 42 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
The first sample says AVX, the code says avx2, and the flag says -mavx
The explicit-instruction-set example is where the documentation stops agreeing with itself. The prose introduces it as computing a mean over two sets of four doubles while assuming the AVX extension is supported. The code below that sentence names AVX2. And the instruction after the sample tells the reader to enable the AVX extension, adding that with gcc or clang this is done with the `-mavx` flag, and on MSVC you pass `/arch:AVX`.
So three parts of one example name two different instruction sets, and the compiler flag offered enables the weaker of the two. `xs::batch<double, xs::avx2>` requests the AVX2 batch type while `-mavx` turns on AVX and leaves AVX2 off.
#include <iostream>
#include "xsimd/xsimd.hpp"
namespace xs = xsimd;
int main(int argc, char* argv[])
{
xs::batch<double, xs::avx2> a = {1.5, 2.5, 3.5, 4.5};
xs::batch<double, xs::avx2> b = {2.5, 3.5, 4.5, 5.5};
auto mean = (a + b) / 2;
std::cout << mean << std::endl;
return 0;
}The rest of the sample is sound. Both operands are four doubles, which is one AVX2 register wide, the arithmetic uses the ordinary operators on a batch rather than an intrinsic call, and the printed result `(2.0, 3.0, 4.0, 5.0)` shows a batch streaming out as a parenthesised list. The arithmetic works out element by element, since each pair averages to the value printed opposite it. What does not work out is the flag.
The vectorised loop computes a rounded-down length and drops the tail
The auto-detection example is a plain function over two vectors of doubles with a result vector, and its loop body is where the useful detail sits. It reads the compile-time batch width as `xsimd::simd_type<double>::size`, then computes `vec_size` as the input size minus `size % simd_size`. The loop walks from zero to `vec_size` in steps of the batch width, loading aligned pairs, averaging them and storing the result.
Rounding that length down means the final `size % simd_size` elements are outside the loop. With a width of four, a caller passing three or five or seven doubles gets only the leading full batch written, and the remainder of the result vector keeps whatever it held before. Nothing in the code reports the shortfall, so a short input is not an error and produces no diagnostic; it just produces an incomplete result.
That is the ordinary shape for hand-written SIMD, and the library is not at fault for it. It matters because this is the pattern the documentation offers as the replacement for naming an instruction set, so the choice of how to handle the remainder moves from the reader to whoever copies the snippet. The printed listing also stops partway through the store statement, after the opening of `bres.st`, so the alignment of the write is left to the reader.
Version 8 is a complete rewrite and the migration guide is still promised
The usage section opens by stating that version 8 of the library is a complete rewrite, with slight differences from the 7.x versions, and that a migration guide will be available soon. The sentence after that says that in the meanwhile the examples show how to use both versions 7 and 8, and it ends on a question mark rather than a full stop.
So the two versions are documented as incompatible, the document for moving between them does not exist yet, and the samples that follow are supposed to cover both. The history section adds a second version marker: it says the design described in the original blog articles remained close to the actual architecture of Xsimd up until version 8.0. That places the break at a specific point in the project's life rather than treating it as an ordinary release.
The practical effect on a user is that the samples cannot be read as a stable reference. A snippet valid for 7.x may not compile against 8.x and the same document does not say which is which, because the promised guide is the thing that would settle it. The xtl dependency table gives a hint of the scale of the change, listing a master row above version rows from 12.x down to 8.x.
The xtl compatibility table has six rows that are all the same range
The dependencies section presents a two-column table pairing xsimd versions against xtl versions, which reads like the compatibility matrix a library author would check before pinning. Every row gives the same answer. Master, 12.x, 11.x, 10.x, 9.x and 8.x are each paired with `^0.7.0`.
Six rows of identical content is not a compatibility statement; it is one range repeated under six labels. Its usefulness is narrower than the layout implies, and it also means the table cannot distinguish the pre-rewrite releases from the post-rewrite one, since the 8.x row and the master row are identical.
The dependency itself is optional and narrow. The README says xsimd has an optional dependency on the xtl library, and that the dependency is required only if you want vectorisation support for `xtl::xcomplex`. A project that does not touch complex numbers from xtl can ignore the whole arrangement. That is a much smaller coupling than a table spanning six release lines would suggest, and it is the kind of detail that is easy to miss because the table occupies more space than the sentence explaining it.
SVE and RISC-V appear as fixed widths, not as scalable vectors
The supported instruction set table lists ten families. On x86 it covers SSE2 through SSE4.2, AVX, AVX2 and three separate FMA3 combinations, then a second x86 row naming AVX512BW, AVX512CD, AVX512DQ, AVX512F and AVX512VL individually, plus FMA4 for AMD. ARM gets NEON, NEON64 and SVE. Then WebAssembly WASM, powerpc64 VSX, RISC-V, LoongArch64 with LSX and LASX, and IBM Z with VXE for z14.
Two rows in that table carry a parenthetical that changes what the entry means. ARM lists SVE128, 256 and 512 with the note fixed vector size, and RISC-V lists RISC-V128, 256 and 512 with the same note. Those architectures are defined around a vector length that is chosen at runtime and can change between instructions, which is the property usually meant by naming them. What appears here instead is a set of three pinned widths per architecture.
So the SVE and RISC-V entries are fixed-size vector types in the shape of the other backends, not an implementation of the scalable vectors those instruction sets introduce. A project that wants length-agnostic code across those architectures will not find it in this table. The FMA handling is similarly shaped: three FMA3 combinations paired with SSE, AVX and AVX2, plus a separate FMA4 for AMD, rather than one FMA entry.
The source install configures in the source directory and calls make install
Three install routes are offered. The first is a package manager:
mamba install -c conda-forge xsimdThe second is Spack, which takes two commands, an install and a load:
spack install xsimd
spack load xsimdThe third builds from sources, and this is the one with a specific shape:
cmake -D CMAKE_INSTALL_PREFIX=your_install_prefix .
make installNote that the trailing `.` makes the source directory the build directory. There is no separate build tree, no `cmake -S . -B build`, and no generator flag, so the configure step writes its cache into the checkout. The second line then calls `make install` directly rather than `cmake --install`, which fixes the generator to a Makefile one at install time even though configure did not ask for it.
Both of those are choices with consequences. An in-source configure leaves generated files in the working tree, which is why the two package manager routes are the ones a casual user is steered toward first. And calling make at the end means the documented source path assumes a Unix-like shell with Make installed, unlike the conda route, which the README notes is available on Windows as well when cmake itself is needed.
Ten CI workflows and no published releases
The README carries a CI table naming ten workflows: android, cross-rvv, cross-sve, cross, cxx-no-exceptions, cxx-versions, emscripten, linux, macos and windows. Each row links to a workflow file of the same name, and each badge is written with empty alt text, so the table renders as a column of nameless status images rather than ten labelled results.
The workflow names describe a test matrix rather than a build. Two of them cross-compile, one for RISC-V vector extensions and one for SVE, which is how code paths for those backends get checked on hardware that does not have them. One builds without exceptions, one varies the compiler version, one targets Emscripten for WebAssembly, and one covers Android. That is a wider matrix than the three-row compiler table below it, which lists only MSVC 2022 and above, g++ 10 and above, and clang 16 and above.
Alongside the table the repository publishes no GitHub releases and no tags, even though a `Changelog.rst` and a `CONTRIBUTING.md` sit at the root. So the version history lives in a file rather than in release artefacts, and a library that a package manager will consume has no named version to pin from the hosting side. The root also holds `install_sde.sh`, which is the route to exercising AVX512 code paths where the hardware does not provide them.
The repository description leaves out three of the ten architectures
The project description reads as a list of instruction sets: SSE, AVX, AVX512, NEON, SVE, WebAssembly, VSX and RISC-V. That is eight names, and it is the version of the list most people will read, since it is what appears in search results and in a dependency graph.
The requirements table has more. Beyond those eight it also carries FMA4 for AMD x86, LoongArch64 with LSX and LASX, and IBM Z with VXE for z14. So three architectures present in the implementation are absent from the one-line description, and two of them, LoongArch64 and IBM Z, are platforms where a reader is most likely to be surprised to find support at all.
The direction of the mismatch is worth noting. The description is not a subset in the sense of listing only what definitely works; it reads as a summary that was written early and not extended as backends were added. Anyone choosing a library by scanning architecture names should read the requirements table instead, since that is the one the build actually follows.
Editorial conclusion
xsimd suits a library author who wants one interface over batches of numbers instead of per-vendor intrinsics, and who can pin a compiler and a target instruction set in their own build. Before depending on it, check five things. Decide whether you need SVE or RISC-V support, because both are offered as fixed 128, 256 and 512 bit variants rather than as the scalable vectors those architectures define. Check whether your build can actually set the flags the API implies, since the first sample in the documentation pairs an avx2 batch type with a compiler flag that enables only AVX. Read the tail-handling in any loop you copy, because the documented pattern computes a rounded-down vector length and leaves the remainder untouched. Treat the version table for xtl as uninformative, since all six rows are the same range. And plan for the 7.x to 8.x rewrite, which the project says is complete while the migration guide remains unwritten.
Frequently asked questions
What does xsimd provide?
C++ wrappers for SIMD intrinsics that let you manipulate batches of numbers with the same arithmetic operators as single values, plus accelerated implementations of common mathematical functions. Its stated purpose is to give library authors one interface, because the underlying instructions differ between microprocessor vendors and compilers.
Which compilers does xsimd officially support?
It builds with any C++17 compliant compiler. Official support covers the compilers tested in CI: Microsoft Visual Studio MSVC 2022 and above, g++ 10 and above, and clang 16 and above.
Which instruction sets does xsimd cover?
Ten families, including SSE through AVX2 with three FMA3 combinations and FMA4 on AMD, AVX512 subsets named individually, NEON and NEON64, SVE at 128, 256 and 512 bit, WebAssembly WASM, powerpc64 VSX, RISC-V at 128, 256 and 512 bit, LoongArch64 LSX and LASX, and IBM Z VXE for z14.
Do I need the xtl library to use xsimd?
Not normally. The dependency on xtl is optional and is required only if you want vectorisation support for xtl::xcomplex. The version table pairs every xsimd line from 8.x to master with the same xtl range of ^0.7.0.
How do I install xsimd?
Three routes are given. From conda-forge, mamba install -c conda-forge xsimd. From Spack, spack install xsimd followed by spack load xsimd. Or from sources, cmake -D CMAKE_INSTALL_PREFIX=your_install_prefix . followed by make install.
Which projects use xsimd?
Beyond Xtensor, the README names Mozilla Firefox, Apache Arrow, Pandas, KDE Krita, Meta Velox, Milvus and Pythran. It also credits Johan Mabille's blog articles as the origin of the project, with the mathematical functions implemented as a lightweight version of algorithms from the deprecated boost.SIMD project.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/xtensor-stack-xsimd)Star history chart for your README
[](https://hysenlabs.com/projects/xtensor-stack-xsimd)Was this useful?