netCDF4 Python Interface

Warnings

• breaking Starting with version 1.7.4 and when using free-threaded Python (e.g., Python 3.13+ with `PYTHON_FREETHREADING=1`), `netcdf4-python` may experience segfaults if `netCDF4` functions are called from multiple threads concurrently. The underlying `netcdf-c` library is not thread-safe, and while `netcdf4-python` has internal locking, care must be taken.
  Fix: Users must ensure that all calls to `netCDF4` library functions are made from a single thread, or implement external threading locks if concurrent access is absolutely necessary.
• gotcha Installation via `pip` usually provides pre-compiled binary wheels that bundle the necessary `netCDF C` and `HDF5 C` libraries. However, if building from source, or on less common systems, these external C libraries must be installed separately and configured correctly (e.g., via `nc-config` or environment variables) for `netcdf4-python` to compile and function.
  Fix: For ease of installation, use `conda` (`conda install netcdf4`) or ensure your system has the `netCDF C` and `HDF5 C` libraries installed and discoverable by the Python build process (e.g., by setting `NETCDF4_DIR` or `LD_LIBRARY_PATH`).
• breaking Prior to version 1.4.0, `netcdf4-python` would only return masked arrays if a slice of data explicitly contained missing values. From version 1.4.0 onwards, the default behavior changed to always return masked arrays for primitive and enum data types if `missing_value` or `_FillValue` attributes are defined, regardless of whether the slice contains actual missing data.
  Fix: To revert to the pre-1.4.0 behavior (return unmasked NumPy arrays unless missing values are present), use `Dataset.set_auto_mask(False)` or `Variable.set_auto_mask(False)` after opening the dataset. Alternatively, adapt your code to expect masked arrays by default.
• deprecated Many examples and older codebases use `datetime.datetime.utcnow()` when assigning time attributes (e.g., to `nc.history`). Python's `datetime.utcnow()` is deprecated and will raise `DeprecationWarning` in modern Python versions, scheduled for removal in future versions.
  Fix: Replace `datetime.datetime.utcnow()` with `datetime.datetime.now(datetime.timezone.utc)` for timezone-aware UTC datetimes, or `datetime.datetime.now(datetime.UTC)` in Python 3.11+. Remember to import `datetime` and `timezone` from the `datetime` module.
• breaking Versions 1.7.0 and 1.7.1 introduced a regression that prevented opening remote OPeNDAP files, resulting in `curl` errors. This issue was likely resolved in subsequent patch releases.
  Fix: If encountering issues with remote OPeNDAP file access on these specific versions, upgrade to a newer patch release (e.g., 1.7.2 or later) or downgrade to a stable prior version (e.g., 1.6.5).

Install

• pip install netCDF4 PyPI (recommended)
• conda install -c conda-forge netcdf4 Conda (recommended for easier dependency management)

Imports

• Dataset

  from netCDF4 import Dataset

  The primary class for opening, creating, and interacting with NetCDF files.

Quickstart

This quickstart demonstrates how to create a NetCDF4 file, define dimensions (including an unlimited dimension for time), create variables with attributes, write NumPy array data into these variables, and then read the data back. It uses `Dataset` for file operations and `numpy` for data generation.

import os
from netCDF4 import Dataset
import numpy as np

# Define a dummy NetCDF file path
filename = 'example.nc'

# Create a new NetCDF file in write mode ('w')
with Dataset(filename, 'w', format='NETCDF4') as nc_file:
    # Create dimensions
    nc_file.createDimension('x', 10)
    nc_file.createDimension('y', 5)
    nc_file.createDimension('time', None) # 'None' for unlimited dimension

    # Create variables
    x_var = nc_file.createVariable('x', 'i4', ('x',))
    y_var = nc_file.createVariable('y', 'i4', ('y',))
    time_var = nc_file.createVariable('time', 'f8', ('time',))
    data_var = nc_file.createVariable('temperature', 'f4', ('time', 'y', 'x'))

    # Add attributes to variables
    data_var.units = 'Celsius'
    data_var.long_name = 'Air Temperature'

    # Write data to variables
    x_var[:] = np.arange(10)
    y_var[:] = np.arange(5)
    
    # Write data for the first time step
    time_var[0] = 0.0
    data_var[0, :, :] = np.random.rand(5, 10) * 30 + 273.15 # Kelvin example
    
    # Write data for a second time step (demonstrates unlimited dimension)
    time_var[1] = 1.0
    data_var[1, :, :] = np.random.rand(5, 10) * 30 + 273.15

    print(f"Successfully created and wrote to {filename}")

# Read data from the NetCDF file in read mode ('r')
with Dataset(filename, 'r') as nc_file:
    print(f"\nOpened {filename} for reading:")
    print(f"File format: {nc_file.data_model}")
    print(f"Dimensions: {list(nc_file.dimensions.keys())}")
    print(f"Variables: {list(nc_file.variables.keys())}")

    temp_data = nc_file.variables['temperature'][:, :, :]
    print(f"Shape of 'temperature' data: {temp_data.shape}")
    print(f"Units of 'temperature': {nc_file.variables['temperature'].units}")
    print(f"Sample temperature data:\n{temp_data[0, 0, 0]:.2f} {nc_file.variables['temperature'].units}")

# Clean up the created file
os.remove(filename)
print(f"\nCleaned up {filename}")