.NC File Format – HDF5 mapping

NetCDF-4

A NetCDF-4 file is an HDF5 file written by the NetCDF library under the conventions in the “NetCDF-4 format” part of Unidata’s file format specification, read 2026-11-12. This page lists how each NetCDF object is stored.

Objects

NetCDFHDF5
GroupGroup. The root group is /. Global attributes become attributes of each group.
VariableDataset with the same name. If a variable has a dimension’s name but is not its coordinate variable, the dataset name gets the prefix _nc4_non_coord_.
AttributeAttribute on the group or dataset.
Dimension with a coordinate variableThe variable’s dataset, made an HDF5 dimension scale of the same type, holding the coordinate data.
Dimension without a variableAn empty dimension scale of type char; only its name and length matter. Its NAME attribute is This is a netCDF dimension but not a netCDF variable.
Variable’s dimensionsHDF5 dimension scales, with the attributes the HDF5 dimension scale API keeps: CLASS, NAME, REFERENCE_LIST, DIMENSION_LIST. When NetCDF writes, every dimension has a scale.

Hidden attributes

AttributeOnMeaning
_NCPropertiesRoot groupProvenance: the versions of the NetCDF and HDF5 libraries that created the file.
_Netcdf4DimidDimension scalesScalar int: the zero-based dimension ID, written (from NetCDF 4.1) when dimensions and coordinate variables were defined in different orders. If any scale has it, all must.
_Netcdf4CoordinatesMulti-dimensional coordinate variablesInt array: the dimension IDs of the variable, because HDF5 cannot attach scales to scales.
_nc3_strictRoot groupScalar int. The file was created with the classic model flag, so the library refuses enhanced-model features such as groups, new primitive types and user-defined types.

The NetCDF API hides these and the dimension scale attributes. From NetCDF 4.1 the library can also read HDF5 files without dimension scales, making up a dimension for each new length it meets; that is read-only, and datasets must have scales for every dimension or none.

Types and values

  • The atomic types map to HDF5 native types: NC_BYTE signed char, NC_UBYTE unsigned char, NC_SHORT/NC_USHORT, NC_INT/NC_UINT, NC_INT64/NC_UINT64 (long long), NC_FLOAT, NC_DOUBLE; NC_CHAR is H5T_C_S1 and NC_STRING a variable-length array of H5T_C_S1.
  • Data is written in the writing machine’s byte order unless the user sets one for a variable; HDF5 swaps on reading as needed.
  • Each user-defined type corresponds exactly to an HDF5 user-defined type; only base types that NetCDF-4 has may be used (no HDF5 reference types).
  • Compression: NetCDF-4 writes only zlib (deflate levels 1 to 9; asking for 0 turns deflation off). It can read szip data if its HDF5 library supports it, but cannot write it.
  • The library writes variables in creation order.