Installation

Version 1.12.0.0 for version 1.12 of the CF conventions.

Note

The latest version to be released and the newest versions available from the Python package index (PyPI) and conda are confirmed at the top of the README document.

Operating systems

cfdm works for Linux, Mac and Windows operating systems.

Python versions

cfdm works for Python versions 3.9 or newer.

pip

To install cfdm and all of its dependencies (apart from UDUNITS) run, for example:

Install as root, with any missing dependencies.
$ pip install cfdm
Install as a user, with any missing dependencies.
$ pip install cfdm --user

To install cfdm without any of its dependencies then run, for example:

Install as root without installing any of the dependencies.
$ pip install cfdm --no-deps

See the documentation for pip install for further options.

UDUNITS

UDUNITS (a C library that provides support for units of physical quantities) is a required dependency that is not installed by pip, but it can be installed in a conda environment:

$ conda install -c conda-forge udunits2

Alternatively, UDUNITS is often available from operating system software download managers, or may be installed from source.

Note that some environment variables might also need setting in order for the UDUNITS library to work properly, although the defaults are usually sufficient.

conda

The cfdm package is in the conda-forge conda channel. To install cfdm with all of its dependencies run

Install with conda.
$ conda install -c conda-forge cfdm udunits2

Note that some environment variables might also need setting in order for the UDUNITS library to work properly, although the defaults are usually sufficient.

Source

To install from source:

  1. Download the cfdm package from https://pypi.org/project/cfdm

  2. Unpack the library (replacing <version> with the version that you want to install, e.g. 1.11.0.0):

    $ tar zxvf cfdm-<version>.tar.gz
$ cd cfdm-<version>

  3. Install the package:

  • To install the cfdm package to a central location:

    $ python setup.py install

  • To install the cfdm package locally to the user in the default location:

    $ python setup.py install --user

  • To install the cfdm package in the <directory> of your choice:

    $ python setup.py install --home=<directory>

Note that some environment variables might also need setting in order for the UDUNITS library to work properly, although the defaults are usually sufficient.

cfdump utility

During installation the cfdump command line utility is also installed, which generates text descriptions of the field constructs contained in a netCDF dataset.

Tests

Tests are run from within the cfdm/test directory:

$ python run_tests.py

Dependencies

The cfdm package requires:

  • Python, version 3.9 or newer.

  • numpy, version 2.0.0 or newer.

  • netCDF4, version 1.7.2 or newer.

  • cftime, version 1.6.4 or newer.

  • h5netcdf, version 1.3.0 newer.

  • h5py, version 3.12.1 or newer.

  • s3fs, version 2024.6.0 or newer.

  • dask, versions 2025.2.0 or newer.

  • packaging, version 20.0 or newer.

  • scipy, version 1.10.0 or newer.

  • uritools, version 4.0.3 or newer.

  • cfunits, version 3.3.7 or newer.

  • UNIDATA UDUNITS-2 library, version 2.2.25 or newer. UDUNITS-2 is a C library that provides support for units of physical quantities.

    If the UDUNITS-2 shared library file (libudunits2.so.0 on GNU/Linux or libudunits2.0.dylibfile on MacOS) is in a non-standard location then its directory path should be added to the LD_LIBRARY_PATH environment variable.

    It may also be necessary to specify the location (directory path and file name) of the udunits2.xml file in the UDUNITS2_XML_PATH environment variable, although the default location is usually correct. For example, export UDUNITS2_XML_PATH=/home/user/anaconda3/share/udunits/udunits2.xml. If you get a run-time error that looks like assert(0 == _ut_unmap_symbol_to_unit(_ut_system, _c_char_p(b'Sv'), _UT_ASCII)) then setting the UDUNITS2_XML_PATH environment variable is the likely solution.

Code repository

The source code is available at https://github.com/NCAS-CMS/cfdm