C++ API used for read/write *.npy/*.npz files
A modern C++20 library for reading and writing NumPy .npy and .npz files, originally forked from rogersce/cnpy (see original README).
-fno-rtti, -fno-exceptions on GCC/Clang; /GR-, /EHs-c- on MSVC): Uses compile-time npypp::detail::Traits<T> instead of std::type_info, and reports fatal I/O or format errors via std::cerr, assert(false), and std::abort().fseeko/ftello on POSIX, _fseeki64/_ftelli64 on Windows) and POSIX mmap / Win32 file-mapping backends in mm::MemoryMappedFile..npy File Support (Save, Append, Load, LoadFull):
.npy format v1.0, v2.0, and v3.0 headers; writes v1.0 (or v2.0 automatically for long headers).float, double, long double, signed/unsigned integers (char/short/int/long/long long), bool, and std::complex<T>.<, >, and = endianness automatically (byte-swapping when needed)."w", "a") and typed FileOpenMode (Write, Append, Read).MultiDimensionalArray<T>, Vector<T>, Matrix<T>, and Tensor<T> (accepted directly by npypp::Save)..npz Archive Support (SaveCompressed, LoadCompressed, LoadCompressedFull):
zlib-deflated .npz entries.LoadCompressed<T>(zipFileName, vectorName) / LoadCompressedFull<T>(...)) without decompressing unrelated entries..npy I/O (mm::MemoryMappedFile):
.npy files (useMemoryMap = true or explicit mm::MemoryMappedFile).npypp::LoadSpan<T>(mmf, &shape) (std::span<const T>) and npypp::Load<T>(ptr, mmf).cmake/ (CmakeUtilities), GitHub Actions CI (Linux + Windows), and GoogleTest unit test suites (NpyTests, cNpyTests, NpyMsanSmoke).fortran_order: False)..npz archive into a map (LoadCompressed<T> / LoadCompressedFull<T>), all entries share the template element type T..npy files (not .npz archives). .npz writing uses stored Zip32 entries (< 4 GiB).LoadSpan / pointer Load requires host-native endianness, matching element size, C-order, and natural alignof(T) alignment in the mapped buffer.Dependencies: CMake 3.28+, Ninja, zlib (zlib1g-dev), and GoogleTest (libgtest-dev, top-level builds only).
cmake -S . --preset=gcc-release
cmake --build --preset=gcc-release
ctest --preset=gcc-release --output-on-failure
Dependencies: Visual Studio / MSVC (C++20), CMake 3.28+, Ninja, and vcpkg (zlib, gtest with the x64-windows-static-md triplet to match the /MD runtime). Run from an x64 Native Tools Developer Command Prompt:
vcpkg install zlib:x64-windows-static-md gtest:x64-windows-static-md
cmake -S . --preset=msvc-release -DCMAKE_TOOLCHAIN_FILE=<vcpkg-root>\scripts\buildsystems\vcpkg.cmake -DVCPKG_TARGET_TRIPLET=x64-windows-static-md
cmake --build --preset=msvc-release
ctest --preset=msvc-release --output-on-failure
See cmake/README.md for all available compiler (gcc-*, clang-*, msvc-*, etc.), sanitizer, LTO, PGO, coverage, and CUDA presets.
.npy and .npz Serialization#include <Npy++.h>
#include <cassert>
#include <cstddef>
#include <vector>
int main()
{
const std::vector<std::size_t> shape { 4, 4, 8 };
const std::vector<double> vec(128, 0.01);
// Serialize using stdio (FILE*)
npypp::Save("arr1.npy", vec, shape, "w");
// Deserialize using memory mapping
const auto useMemoryMapping = true;
const auto loadedData = npypp::LoadFull<double>("arr1.npy", useMemoryMapping);
assert(loadedData.shape == shape);
assert(loadedData.data == vec);
// Compressed archives (.npz)
npypp::SaveCompressed("arr1.npz", "arr1", vec, shape, "w");
const auto loadedCompressedData = npypp::LoadCompressedFull<double>("arr1.npz", "arr1");
assert(loadedCompressedData.shape == shape);
assert(loadedCompressedData.data == vec);
}
#include <Npy++.h>
#include <cassert>
#include <cstddef>
#include <functional>
#include <numeric>
#include <vector>
int main()
{
const std::vector<std::size_t> shape { 4, 4, 8 };
const std::vector<double> vec(128, 0.01);
const auto nElements = std::accumulate(shape.begin(), shape.end(), std::size_t{ 1 }, std::multiplies<std::size_t>());
const auto npyHeader = npypp::detail::GetNpyHeader<double>(shape);
const auto fileSizeBytes = npyHeader.size() + nElements * sizeof(double);
// Open the file with read/write memory mapping (size must be known upfront)
mm::MemoryMappedFile<mm::CacheHint::SequentialScan, mm::MapMode::ReadAndWrite> mmf("arr1_mmap.npy", fileSizeBytes);
assert(mmf.IsValid());
npypp::Save(mmf, vec, shape);
// Rewind mapped cursor before reading back
mmf.Rewind();
// Zero-copy std::span view directly into the mapped .npy buffer
std::vector<std::size_t> loadedShape;
const auto spanView = npypp::LoadSpan<double>(mmf, &loadedShape);
assert(loadedShape == shape);
assert(spanView.size() == vec.size());
for (std::size_t i = 0; i < vec.size(); ++i)
assert(vec[i] == spanView[i]);
}