Install & Compatibility
Where this runs
tested against v1.8.1 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
95MB installed
● package 95MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
File
✓ from h5netcdf import File
Main class for interacting with NetCDF4 files in the new API.
Dataset
✓ from h5netcdf.legacyapi import Dataset
Entry point for the legacy API, designed for netCDF4-python users.
This quickstart demonstrates how to create a NetCDF4 file, define dimensions, create a variable, write data, add an attribute, create a group, and then read the data back using the `h5netcdf.File` (new API) interface.
import h5netcdf
import numpy as np
import os
file_path = 'my_test_data.nc'
# Write data using the new API
with h5netcdf.File(file_path, 'w') as f:
f.dimensions = {'x': 5, 'y': 3}
var = f.create_variable('temperature', ('x', 'y'), 'f4')
var[:] = np.random.rand(5, 3)
var.units = 'Kelvin'
f.create_group('forecast_data')
print(f"Successfully wrote data to {file_path}")
# Read data
with h5netcdf.File(file_path, 'r') as f:
print(f"Dimensions: {list(f.dimensions.keys())}")
temp = f.variables['temperature']
print(f"Variable 'temperature' shape: {temp.shape}")
print(f"Variable 'temperature' units: {temp.units}")
print(f"First few values: {temp[:2, :2]}")
if 'forecast_data' in f.groups:
print("Group 'forecast_data' exists.")
# Clean up
os.remove(file_path)
Debug
Known issues
breakingWith h5py version 3.0+, the default behavior for decoding variable-length strings changed from automatically decoding to UTF-8 strings to returning arrays of bytes. To restore the automatic decoding behavior that matches the legacy h5py API and netCDF4-python, explicitly set `decode_vlen_strings=True` in the `h5netcdf.File` constructor.fixPass `decode_vlen_strings=True` to `h5netcdf.File()` constructor when opening files with variable-length strings, or handle byte arrays directly.
affects: h5netcdf versions using h5py 3.0+
breakingThe `track_order` parameter's default behavior changed in h5netcdf 1.1.0 to `True` (if h5py >= 3.7.0 is detected) for *newly created* netCDF4 files. This ensures compatibility with netCDF4-c. However, files created with older versions of h5netcdf (e.g., 1.0.2 and older, except for 0.13.0) where `track_order=False` was effectively or explicitly set, will continue to open with order tracking disabled in newer h5netcdf versions, potentially leading to interoperability issues if external netCDF4-c tools expect ordered dimensions/variables.fixFor new files, ensure `h5py >= 3.7.0` is installed (h5netcdf will default to `track_order=True`). For existing files created with older versions, be aware that order tracking might be disabled upon reopening; if compatibility with netCDF4-c append operations is critical, recreation with `track_order=True` might be necessary, or explicitly setting the parameter if using older h5py versions.
affects: All versions, especially when migrating files created with h5netcdf < 1.1.0 or h5py < 3.7.0.
gotchaBy default, `h5netcdf` raises a `CompatibilityError` if you attempt to write HDF5 features (like certain data types or arbitrary filters) that are not considered valid NetCDF4 by other tools. While these are valid HDF5, they break NetCDF compatibility. In versions prior to 0.7.3, this was merely a warning.fixTo allow writing these non-NetCDF4 compliant HDF5 features, pass `invalid_netcdf=True` to the `h5netcdf.File()` constructor. Be aware that such files may not be readable by other netCDF tools.
affects: All versions, with stricter enforcement since ~0.7.3
gotchaIf you access variables in an HDF5 file that have no dimension scale associated with one of their axes, `h5netcdf` will raise a `ValueError`. This often occurs with non-NetCDF HDF5 files.fixWhen opening the file, set `phony_dims='sort'` in `h5netcdf.File()` to instruct `h5netcdf` to invent phony dimensions, mimicking standard NetCDF behavior. Alternatively, `phony_dims='access'` can defer phony dimension creation to access time, but with different naming conventions.
affects: All versions
gotchaWhen using the new API, automatic resizing of unlimited dimensions with array indexing (e.g., `variable[i, :] = data`) is *not* available. This differs from the `netCDF4-python` library's behavior.fixManually resize dimensions using `group.resize_dimension(dimension, size)` before writing data that would exceed the current dimension size.
affects: All versions (new API)
gotchaRepeated access to properties that rely on the underlying `_h5ds` HDF5 dataset object can be costly in terms of performance, as `_h5ds` is created on demand. This can impact workflows that frequently query properties like `variable.shape` in a loop.fixCache the `_h5ds` object or its relevant properties if they are accessed repeatedly in a performance-critical loop. For example, store `variable.shape` in a local variable if it's constant for the loop's duration.
affects: All versions
gotchaIf you initialize `h5netcdf.File` by passing an existing `h5py.File` object (e.g., `h5netcdf.File(h5py_file_obj)`), closing the `h5netcdf.File` wrapper will *not* close the underlying `h5py.File` object. However, if the file is opened by path (e.g., `h5netcdf.File('mydata.nc')`), closing the `h5netcdf.File` *will* close the underlying HDF5 file.fixWhen wrapping an `h5py.File` object, ensure you explicitly close the original `h5py.File` object when it's no longer needed to release resources.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'numpy'
As of h5netcdf version 1.8.0, `h5py` (and implicitly `numpy`) was dropped as a strict dependency to allow for alternative backends like `h5pyd` or `pyfive`, requiring users to explicitly install `h5py` or another backend alongside `h5netcdf`.
fixInstall h5py and its dependencies (like numpy) explicitly using `pip install h5netcdf[h5py]` or `conda install h5netcdf h5py`.
PermissionError: [Errno 13] Permission denied: 'filename.nc'
This error occurs when the Python process does not have the necessary write permissions for the directory where it's attempting to create or modify a NetCDF file, or if the specified directory path does not exist.
fixEnsure the target directory exists and the Python script has write permissions for that directory. Alternatively, specify a full path to a directory where writing is permitted.
h5netcdf.CompatibilityError: HDF5 feature '...' is not supported by netCDF4. Set invalid_netcdf=True to write an invalid netCDF file.
h5netcdf strictly enforces netCDF4 compatibility by default, meaning certain HDF5 features (e.g., specific data types like Booleans or reference types, or arbitrary filters) cannot be written if they would result in a file unreadable by other netCDF tools.
fixIf netCDF compatibility with other tools is not required, explicitly allow writing non-compliant HDF5 features by setting `invalid_netcdf=True` when creating the file: `f = h5netcdf.File('mydata.h5', invalid_netcdf=True)`. ValueError: variable 'var_name' has no dimension scale along axis 0
This error typically occurs when reading HDF5 files that lack explicit dimension scales, which are expected by h5netcdf to correctly interpret netCDF-like dimensions.
fixWhen opening the file, set the `phony_dims` parameter to 'sort' or 'access' to instruct h5netcdf to invent phony dimensions, mimicking netCDF behavior: `f = h5netcdf.File('mydata.h5', mode='r', phony_dims='sort')`. AttributeError: 'File' object has no attribute 'createDimension'
This error arises when attempting to use legacy API methods like `createDimension` directly on an `h5netcdf.File` object, which is part of the new API. Dimension and variable creation methods differ between h5netcdf's new and legacy APIs.
fixUse the appropriate new API methods for dimension and variable creation, such as assigning to `f.dimensions` or `f.create_variable()`, or explicitly use the legacy API by importing `h5netcdf.legacyapi.Dataset`.
Upgrade
Version history
1.8.1latest on PyPI · released Jan 23, 2026
Audit
Dependencies
pythonrequiredRequires Python 3.9 or newer.
h5pyrequiredPrimary backend for HDF5 I/O. Required for full functionality and commonly installed via `h5netcdf[h5py]` extra.
numpyrequiredFundamental package for numerical computing, used for data arrays.
pyfiveoptionalOptional pure-Python HDF5 reading backend, installed via `h5netcdf[pyfive]` extra.
h5pydoptionalOptional backend for HDF5 REST API, installed via `h5netcdf[h5pyd]` extra.