It is highly recommended that you use a pre-built version of h5py, either from a Python Distribution, an OS-specific package manager, or a pre-built wheel from PyPI.

Be aware however that most pre-built versions lack MPI support, and that they are built against a specific version of HDF5. If you require MPI support, or newer HDF5 features, you will need to build from source.

After installing h5py, you should run the tests to be sure that everything was installed correctly. This can be done in the python interpreter via:

import h5py

Source installation

To install h5py from source, you need three things installed:

  • A supported Python version with development headers
  • Cython >=0.29
  • HDF5 1.8.4 or newer with development headers
  • A C compiler

On Unix platforms, you also need pkg-config unless you explicitly specify a path for HDF5 as described in Custom installation.

OS-specific instructions for installing HDF5, Python and a C compiler are in the next few sections.

Additional Python-level requirements should be installed automatically (which will require an internet connection).

The actual installation of h5py should be done via:

$ pip install --no-binary=h5py h5py

or, from a tarball or git checkout

$ pip install -v .

If you are working on a development version and the underlying cython files change it may be necessary to force a full rebuild. The easiest way to achieve this is

$ git clean -xfd

from the top of your clone and then rebuilding.

Source installation on OSX/MacOS

HDF5 and Python are most likely in your package manager (e.g. Homebrew, Macports, or Fink). Be sure to install the development headers, as sometimes they are not included in the main package.

XCode comes with a C compiler (clang), and your package manager will likely have other C compilers for you to install.

Source installation on Linux/Other Unix

HDF5 and Python are most likely in your package manager. A C compiler almost definitely is, usually there is some kind of metapackage to install the default build tools, e.g. build-essential, which should be sufficient for our needs. Make sure that that you have the development headers, as they are usually not installed by default. They can usually be found in python-dev or similar and libhdf5-dev or similar.

Source installation on Windows

Installing from source on Windows is a much more difficult prospect than installing from source on other OSs, as not only are you likely to need to compile HDF5 from source, everything must be built with the correct version of Visual Studio. Additional patches are also needed to HDF5 to get HDF5 and Python to work together.

We recommend examining the appveyor build scripts, and using those to build and install HDF5 and h5py.

Custom installation


Remember that pip installs wheels by default. To perform a custom installation with pip, you should use:

$ pip install --no-binary=h5py h5py

or build from a git checkout or downloaded tarball to avoid getting a pre-built version of h5py.

You can specify build options for h5py as environment variables when you build it from source:

$ HDF5_DIR=/path/to/hdf5 pip install --no-binary=h5py h5py
$ HDF5_VERSION=X.Y.Z pip install --no-binary=h5py h5py
$ CC="mpicc" HDF5_MPI="ON" HDF5_DIR=/path/to/parallel-hdf5 pip install --no-binary=h5py h5py

The supported build options are:

- To specify where to find HDF5, use one of these options:
  • HDF5_LIBDIR and HDF5_INCLUDEDIR: the directory containing the compiled HDF5 libraries and the directory containing the C header files, respectively.
  • HDF5_DIR: a shortcut for common installations, a directory with lib and include subdirectories containing compiled libraries and C headers.
  • HDF5_PKGCONFIG_NAME: A name to query pkg-config for. If none of these options are specified, h5py will query pkg-config by default for hdf5, or hdf5-openmpi if building with MPI support.
  • HDF5_MPI=ON to build with MPI integration - see Building against Parallel HDF5.
  • HDF5_VERSION to force a specified HDF5 version. In most cases, you don’t need to set this; the version number will be detected from the HDF5 library.

Building against Parallel HDF5

If you just want to build with mpicc, and don’t care about using Parallel HDF5 features in h5py itself:

$ export CC=mpicc
$ pip install --no-binary=h5py h5py

If you want access to the full Parallel HDF5 feature set in h5py (Parallel HDF5), you will further have to build in MPI mode. This can be done by setting the HDF5_MPI environment variable:

$ export CC=mpicc
$ export HDF5_MPI="ON"
$ pip install --no-binary=h5py h5py

You will need a shared-library build of Parallel HDF5 as well, i.e. built with ./configure --enable-shared --enable-parallel.