# h5py: the Python binding that keeps HDF5 in reach

> h5py wraps The HDF Group binary format in a Python API, ships wheels for CPython 3.11 and up, and puts large array workloads behind a dictionary-like interface. Here is what the repository itself shows.

**h5py/h5py** — HDF5 for Python -- The h5py package is a Pythonic interface to the HDF5 binary data format.

- Repository: https://github.com/h5py/h5py
- Website: http://www.h5py.org
- Stars: 2,253 · Forks: 571
- Language: Python
- License: BSD-3-Clause
- Published: 2026-10-06 · Updated: 2026-10-06 · Language: en
- Canonical page: https://hysenlabs.com/projects/h5py-h5py

## A thin binding over somebody else's binary format

The repository calls h5py a "thin, pythonic wrapper" around HDF5, and that adjective is the most useful word in the README. There is no server, no daemon and no storage engine of its own. What ships is a CPython extension module binding the HDF5 C library, plus a Python layer shaped like dictionaries and NumPy arrays on top of it.

The build files make the division of labour explicit. The docstring in `setup.py` says most of the functionality is provided in two separate modules, `setup_configure`, which manages compile-time and Cython-time build options, and `setup_build`, which handles the actual compilation. The surface you program against is therefore small and slow-moving, while the machinery needed to produce a binary wheel for a given NumPy and Python combination is substantial.

`pyproject.toml` files the project under Development Status 5, Production/Stable, and gives it two topics that pull in different directions: Scientific/Engineering and Database. That pairing is honest about what the library became, because much of its traffic comes from instrument and detector pipelines that write large numeric arrays into a layout they can query by attribute months later.

## Four install routes, and which one avoids a compiler

Getting h5py onto a machine is mostly a matter of not compiling it. The README lists four routes: a Python distribution such as Continuum Anaconda or Enthought Canopy, PyPI via pip, the many Linux distributions that package it, and on macOS the package managers Homebrew, Macports or Fink. The pip route is what most readers will use, and it is deliberately short.

```bash
python -m pip install h5py
```

There is no virtual environment step and no version pin, which says the project assumes you have already decided how you manage environments.

The Python floor is worth pinning down because it has moved. The README says h5py runs on Python 3, specifically 3.11 and newer, and `pyproject.toml` sets `requires-python = ">=3.11"` with classifiers for 3.11, 3.12, 3.13 and 3.14. One classifier reads `Python :: Free Threading :: 1 - Unstable`, a candid admission that free-threaded builds exist without being treated as a supported configuration. More detailed instructions, including how to produce a build with MPI support, live at docs.h5py.org/en/latest/build.html.

## The build dependency list tells you what a wheel has to match

When no wheel is available, the build is where the friction lives, and the dependency list in `pyproject.toml` is unusually readable for a compiled project.

```toml
requires = [
    "Cython >=3.0.0, <4",
    "numpy >=1.25.0, <3",
    "packaging >=23.0",
    "pkgconfig >=1.5.5",
    "setuptools >=77.0.1",
]
```

Two entries stand out. Cython is held below 4.0, so the build is tied to a major Cython line the maintainers have chosen to support. NumPy spans 1.25 up to 3, a wide range, and it is there for the array interface rather than for anything h5py computes.

The build backend is in-tree. `build-backend = "backend"` with `backend-path = ["_custom_build"]`, described in a comment as extending setuptools.build_meta, exists so the build can inspect the local HDF5 and pkgconfig situation before deciding what to compile. Around it sit the files of a project with real release discipline: `ci/`, `appveyor.yml`, `azure-pipelines.yml`, `tox.ini`, `pytest.ini`, a `.pre-commit-config.yaml` and `asv.conf.json` for benchmarks. `dev-install.sh` sits next to `setup.py` and `setup_build.py` as the developer entry point. The version string is declared twice and the project admits it: `version = '3.17.0dev0'` carries a comment to keep it in sync with `h5py.version.version_tuple`.

## Sixteen example files say more than the README does

The README contains no usage example whatsoever, which makes the `examples/` directory the more informative document. Its sixteen files are named after problems rather than API calls.

`collective_io.py` and `swmr_multiprocess.py` both point at multi-process reading and writing, and the two `swmr_` files, `swmr_inotify_example.py` and `swmr_multiprocess.py`, deal with the single-writer, multiple-reader pattern that HDF5 supports and that change notification makes practical. `vds_simple.py` covers virtual datasets, where one logical array is stitched from many stored chunks without copying them. `dataset_concatenation.py` and `multiblockslice_interleave.py` are about how reads and writes map onto the underlying chunk layout.

Three names come from real detector projects: `eiger_use_case.py`, `excalibur_detector_modules.py` and `percival_use_case.py`. Those are beamline science instruments, and their presence is a fair signal about who depends on this library. Two smaller files answer the questions newcomers actually hit first. `bytesio.py` keeps a file in memory rather than on disk, and `store_datetimes.py` exists because a datetime is not one of HDF5's native types and has to be encoded before it can be stored.

## Where a thin wrapper shows its edges

Most of h5py's limits come from the layer underneath it, and the README is not where they are explained. The honest signals sit in the file names and in the classifiers.

Free-threaded Python is classified unstable, which means the GIL-free configuration is available but the project does not stand behind it. That is a threading constraint inherited from the C library, not a gap in the Python wrapper. The concentration on single-writer examples reflects HDF5's locking model: several readers and one writer, with writes serialised by a file lock. Anyone arriving from a database with concurrent transactions will find that narrower, and it is the most common surprise in practice.

The compression story is visible in the tree. There is an `lzf/` directory, and `lzf/LICENSE.txt` is listed among the project license files alongside `LICENSE` and everything under `licenses/`. The LZF filter therefore ships in-tree rather than being loaded from a system plugin at runtime, which removes an install-time dependency at the cost of carrying a second filter implementation. The general shape holds throughout: h5py adds little of its own, which means few surprises, and also means your feature set is whatever the linked C library happens to offer.

## Releases, the two-channel support route, and where the docs take over

Activity is easy to date. The repository is not archived, its default branch is `master`, and the last push was on 2026-09-18. Three releases are recorded: 3.15.0 and 3.15.1 in October 2025, then 3.16.0 on 2026-03-06, with the 3.15 notes pointing at docs.h5py.org. The development version in `pyproject.toml` is 3.17.0dev0, so master sits one feature line past the most recent tag.

The README structure is a map of where responsibility sits. Three websites: h5py.org for the project itself, GitHub for source, and the HDF forum for discussion. Bugs go to GitHub issues and general questions go to the forum, a split worth respecting because the forum is where HDF5-level questions actually get answered rather than closed as upstream.

Everything past installation lives outside the repository page. Build flags, MPI support, performance tuning, SWMR semantics and the low level API are all under docs.h5py.org. Licensing is plain on the surface: BSD-3-Clause, with LICENSE, `lzf/LICENSE.txt` and `licenses/*` declared as license files, which is what a project that vendors third-party code looks like. Whether that arrangement suits your distribution is a question for your own counsel.

## Conclusion

h5py fits one specific shape of work: numeric arrays and metadata that belong in a single file, written by one process and read by many, with no database server involved. It is the wrong choice if you need concurrent writers, if the dataset is small enough to keep in memory anyway, or if compiling anything at all is off the table. Verify three things before committing: the Python and NumPy pair against published wheels, the compression filters your pipeline expects, and the concurrency model your collection code assumes, since the README settles none of the three.

## FAQ

### What is h5py?

h5py is a Python interface to the HDF5 binary data format, described in its README as a thin, pythonic wrapper around the HDF5 library. It lets Python code read and write HDF5 files using dictionaries and NumPy arrays, requires Python 3.11 or newer, and is distributed under BSD-3-Clause.

### Is HDF5 still used?

The HDF5 format is still the reason h5py exists, and the project is still shipping. The most recent recorded release is 3.16.0, published on 2026-03-06, with 3.15.0 and 3.15.1 in October 2025, and the last push to the repository was on 2026-09-18. The project classifies itself for Scientific/Engineering and Database use, which is where the format still shows up.

### How do I open a h5py file?

HDF5 files are opened through the h5py API from Python rather than by a separate viewer, and the README does not show the call, so the documentation site is the reference. The `examples/` directory is the better starting point in the repository itself: `bytesio.py` shows in-memory files, `dataset_concatenation.py` and `vds_simple.py` show how reads are shaped, and `swmr_multiprocess.py` shows the shared-read pattern.

## Sources

- [h5py/h5py on GitHub](https://github.com/h5py/h5py)
- [License: BSD-3-Clause](https://github.com/h5py/h5py/blob/master/LICENSE)
- [Project website](http://www.h5py.org)
- [README](https://github.com/h5py/h5py/blob/master/README.md)
- [Releases](https://github.com/h5py/h5py/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/h5py-h5py