netCDF4: the Python and NumPy face of the netCDF C library

A thin, typed wrapper around netcdf-c

netCDF4 is described in one line as a Python and NumPy interface to the netCDF C library, and the package metadata describes it as providing an object-oriented Python interface to the netCDF version 4 library.

That last word, version 4, matters. netCDF3 and netCDF4 are different formats with different capabilities, and the library covers both: the release notes mention reading NETCDF3 files faster in shared read mode, and support for the classic file formats in parallel through the pnetcdf library. So an existing archive of netCDF3 files and a new netCDF4 file can be handled by the same code.

The data model is the reason people use netCDF at all, and the library exposes it as objects. A dataset holds dimensions, groups and variables, and the variables are read and written as NumPy arrays rather than as buffers you have to shape by hand. The keywords in the package metadata name the fields the library is used for: science, data, network, oceanography, meteorology and climate.

The project is run by Unidata, the same organisation behind the netCDF C library itself, which is why the repository contains the C library as a submodule and why the build script checks for HDF5 headers on the system.

The licence is MIT, and the package is published on PyPI under the name netCDF4, with a conda-forge package as the alternative route.

Installing: wheels, conda and what the C stack needs

The install story has changed a lot over the versions, and the release notes record the progression.

Version 1.7.4 in January 2026 is the one to know about. Compression plugins are now included in the wheels, and wheels for Windows on arm64 and for free-threaded Python are provided. The same release added automatic conversion between character arrays and string arrays for Unicode strings, not just ASCII.

Before that, the wheel story was patchier. Version 1.6.4 in June 2023 made the package require certifi to locate SSL certificates, which is what allows OpenDAP HTTPS URLs to work with the Linux wheels. Version 1.6.0 added working arm64 wheels for Apple M1 Silicon, and version 1.5.5.1 updated the macOS and Linux wheels to link the latest netCDF C and HDF5 libraries.

The alternative to wheels is conda-forge, which the README carries a badge for, and that route is the one to prefer on clusters and HPC systems where the environment is already managed with conda.

Building from source still matters in one situation: when you need a version of the netCDF C library or HDF5 that the wheel does not carry, or when you need parallel IO. The build requirements are Cython, NumPy, setuptools and setuptools_scm, and the version of the package comes from the git tag through setuptools_scm rather than being written in a file.

The current metadata states that Python 3.11 or later is required, and the classifiers list versions from 3.11 through 3.15.

Compression, filters and quantization

The feature that distinguishes netCDF4 from a plain HDF5 reader is the data model with compression on top of it, and the release notes show that area being actively worked on.

Version 1.6.0 added a compression keyword to the variable creation call, supporting szip as well as the new compression algorithms available in netCDF C 4.9.0 through compression plugins, naming zstd, bzip2 and blosc among them. The same release added quantization support, specifically bit-grooming and bit-rounding, which the notes say can dramatically improve compression.

That combination is the point. Quantisation reduces the precision of the stored values so that the compressor has less entropy to squeeze, and with HDF5 filters you can chain them on a variable rather than compressing a whole file with one algorithm.

The library also grew the introspection needed to use those features safely. Version 1.6.1 added methods on the Dataset object to query the availability of the optional compression filters, so a program can ask what the linked library supports instead of guessing and failing at write time.

Version 1.6.1 also released the GIL for all C library calls, which matters for the case where a Python thread waits on a long netCDF read while other threads run. Version 1.7.0 added support for complex numbers through an auto_complex keyword on Dataset.

For anyone assembling files programmatically there is also Dataset.fromcdl and Dataset.tocdl, added in version 1.5.6, which convert between CDL text and datasets, at the price of requiring the ncdump and ncgen utilities on the path.

The threading warning you should read twice

The most important sentence in the README is in the 1.7.4 release notes, and it is a warning.

netcdf-c is not thread-safe, and netCDF4-python does have internal locking, so the expectation is segfaults if you use netCDF4-python on multiple threads with free-threaded Python. The instruction to users is to exercise care and only call netCDF from a single thread.

That is a sharper statement than most libraries make, and it interacts with the rest of the news in the same release. The wheels for free-threaded Python were added, and the GIL had already been released for all C library calls in 1.6.1. In other words, the packaging supports free-threaded interpreters, and the underlying library is not safe for concurrent use from several threads.

The practical reading is that the library is fine on a normal GIL build, where the released GIL does not make netCDF calls genuinely concurrent anyway, and dangerous on a free-threaded build where they can be. If you are building a service that reads netCDF files from a thread pool on a no-GIL interpreter, this is the thing to design around rather than discover in production.

There is an example file named threaded_read.py in the examples directory, which suggests the project is aware of the question and provides something to look at.

Building from source and the limited API option

The build system is Cython on top of setuptools, with the version derived from git tags.

The pyproject file lists Cython, NumPy 2.0 or later, setuptools 77.0.1 or later and setuptools_scm as build requirements, and points the build backend at a path inside the repository, so the build itself lives in the project rather than in setuptools.

The setup script does the unglamorous work of finding the native stack. There is a function that looks for the HDF5 public header in a directory and parses the version macro out of it, printing whether the headers were found, and another that checks for the netCDF header to decide whether netCDF4 support is available in the linked library. The idea is that a source build adapts to the HDF5 and netCDF versions installed on the machine.

There is also an opt-in mode for the stable ABI. An environment variable switches it on, and the setup script applies a further restriction: the Cython, NumPy and limited API combination requires Python 3.11 or later, and as of Python 3.14t the free-threaded builds do not support the limited API at all, so the option is disabled there. When it is enabled, the wheel is tagged for the running interpreter version and can be reused across later versions.

The dependencies of the installed package are small: cftime for the date conventions, certifi for certificate discovery, packaging, and NumPy at 1.23.2 or later. An optional parallel extra pulls in mpi4py, matching the MPI examples in the repository.

Examples, documentation and the wider alternatives

The examples directory is a good map of what people actually do with the library.

There is a tutorial file, notebooks for reading and for writing netCDF, a subset example, an example that reads attributes from JSON, one for complex numbers, one for string arrays, one for threaded reading, and two MPI examples, one of them with compression. Then there is a family of benchmarks, several of them focused on compression and one on diskless operation, which tells you that the performance characteristics of the compression path were measured rather than assumed.

The documentation lives in a docs directory with a shell script to build it, alongside man pages, a changelog, a checkversion script and a separate release readme file.

The honest comparison is with the alternatives in the Python ecosystem, and the difference in approach is the data model. A generic HDF5 library gives you the storage format without the conventions, so you decide how to lay out groups and attributes yourself. netCDF4 gives you the netCDF model on top of that storage, with dimensions, coordinates, units and the grouped filter machinery that the scientific community expects, and it keeps the older netCDF3 files readable through the same interface.

A higher level library such as xarray sits above this one and treats it as one of several backends, which is the arrangement to consider if your analysis code is already written against labelled arrays. And if your data is a plain array in a pickle, none of this applies, because the conventions of netCDF only pay off when the file is meant to be read by other people and other tools.

Editorial conclusion

netCDF4 is the right library when your data is in the netCDF format or its HDF5 base, because it gives you the self describing data model, the grouped compression filters and the parallel IO options that a generic HDF5 reader does not, and it ships wheels for the platforms where compiling would be painful. It is the wrong choice if your data is a plain NumPy array in a pickle, and it is the wrong choice for a multi threaded service on a free-threaded Python build, given the segfault warning in the release notes. Verify first which wheel matches your interpreter, because free-threaded and arm64 wheels were added only in version 1.7.4, and confirm that the netCDF C library and HDF5 you link against are the versions your data was written with.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. Unidata/netcdf4-python on GitHub