Skip to content
Switch branches/tags
Go to file

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time


Azure Pipelines ReadTheDocs Binder Join the Gitter Chat

Reading and writing image, sound and npz file formats to and from xtensor data structures.
Try it live in the browser!


xtensor-io offers an API to read and write various file formats into xtensor data structures:

  • images,
  • audio files,
  • NumPy's compressed storage format (NPZ),
  • HDF5 files,
  • Blosc.

xtensor-io wraps the OpenImageIO, libsndfile, zlib, HighFive, and blosc libraries.


xtensor-io is a header-only library. We provide a package for the conda package manager.

conda install xtensor-io -c conda-forge
  • xtensor-io depends on xtensor ^0.23.0.

  • OpenImageIO, libsndfile, zlib, HighFive, and blosc are optional dependencies to xtensor-io

    • OpenImageIO is required to read and write image files.
    • libsndfile is required to read and write sound files.
    • zlib is required to load NPZ files.
    • HighFive (and the HDF5 library) is required to read and write HDF5 files.
    • blosc is required to read and write Blosc files.

All five libraries are available for the conda package manager.

You can also install xtensor-io from source:

mkdir build
cd build
cmake ..
sudo make install

Trying it online

To try out xtensor-io interactively in your web browser, just click on the binder link:



To get started with using xtensor-io, check out the full documentation


// loads png image into xarray with shape HEIGHT x WIDTH x CHANNELS
auto img_arr = xt::load_image("test.png");

// write xarray out to JPEG image
xt::dump_image("dumptest.jpg", img_arr + 5);

// load npz file containing multiple arrays
auto npy_map = xt::load_npz("test.npz");

auto arr_0 = npy_map["arr_0"].cast<double>();
auto arr_1 = npy_map["arr_1"].cast<unsigned long>();

// open a wav file
auto audio = xt::load_audio("files/xtensor.wav");
auto& audio_arr = std::get<1>(audio); // audio contents (like results)

// save a sine wave sound
int freq = 2000;
int sampling_freq = 44100;
double duration = 1.0;

auto t = xt::arange(0.0, duration, 1.0 / sampling_freq);
auto y = xt::sin(2.0 * xt::numeric_constants<double>::PI * freq * t);

xt::dump_audio("files/sine.wav", y, sampling_freq);


We use a shared copyright model that enables all contributors to maintain the copyright on their contributions.

This software is licensed under the BSD-3-Clause license. See the LICENSE file for details.