Skip to content

installation.rst

Latest commit

 

History

History
320 lines (200 loc) · 8.3 KB

installation.rst

File metadata and controls

320 lines (200 loc) · 8.3 KB
.. currentmodule:: cf

Installation

Version |release| for version |version| of the CF conventions.

Operating systems

The cf package works only for Linux and Mac operating systems.

If you have a Windows operating system then you can use the Microsoft Windows Subsystem for Linux (WSL).

Python versions

The cf package is only for Python 3.10 or newer.

pip

cf is in the Python package index: https://pypi.org/project/cf-python

To install cf and its :ref:`required dependencies <Required>` (apart from :ref:`Udunits <Udunits>`, and there are also some :ref:`optional dependencies <Optional>` which are not automatically installed via pip) run, for example:

$ pip install cf-python
$ pip install cf-python --user

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

$ pip install cf-python --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 :ref:`some environment variables might also need setting <UNIDATA-UDUNITS-2-library>` in order for the Udunits library to work properly, although the defaults are usually sufficient.

See the :ref:`required dependencies <Required>` section for more details.

conda

To install cf with all of its :ref:`required <Required>` and :ref:`optional <Optional>` dependencies, and the cf-plot visualisation package, run:

$ conda install -c conda-forge cf-python cf-plot udunits2
$ conda install -c conda-forge "esmpy>=8.7.0"

The second of the two conda commands is required for :ref:`regridding <Regridding>` to work.

Note that :ref:`some environment variables might also need setting <UNIDATA-UDUNITS-2-library>` in order for the Udunits library to work properly, although the defaults are usually sufficient.

Jupyter Notebooks

You may want to work with cf via a Jupyter Notebook within a conda environment.

A known issue exists for Python 3.12 only when one wants to install the optional dependency ESMPy. Namely, the stricter dependencies of the Jupyter library clash with those of cf (namely zlib required by ESMPy) and installation fails.

A proven workaround is to install Jupyter before installing cf, like so:

$ conda install jupyter
$ conda install -c conda-forge cf-python cf-plot udunits2
$ conda install -c conda-forge "esmpy>=8.7.0"

Source

To install from source (without any dependencies):

  1. Download the cf package from https://pypi.org/project/cf-python

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

    $ tar zxvf cf-python-<version>.tar.gz
$ cd cf-python-<version>

  3. Install the package:

  • To install the cf-python package to a central location:

    $ python setup.py install

  • To install the cf-python package locally to the user in the default location:

    $ python setup.py install --user

  • To install the cf-python package in the <directory> of your choice:

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

Note that :ref:`some environment variables might also need setting <UNIDATA-UDUNITS-2-library>` in order for the Udunits library to work properly, although the defaults are usually sufficient.

cfa utility

During installation the cfa command line utility is also installed, which:

Dependencies

Required

  • Python, 3.10.0 or newer.
  • numpy, versions 2.0.0 or newer.
  • dask, version 2025.5.1 or newer.
  • distributed, version 2025.5.1 or newer.
  • netCDF4, version 1.7.2 only.
  • cftime, version 1.6.4 or newer (note that this package may be installed with netCDF4).
  • scipy, version 1.10.0 or newer.
  • cfdm, version 1.13.0.0 or up to, but not including, 1.13.1.0.
  • cfunits, version 3.3.7 or newer.
  • psutil, version 0.6.0 or newer.
  • packaging, version 20.0 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.

Optional

Some further dependencies that enable further functionality are optional. This to facilitate cf-python being installed in restricted environments for which these features are not required.

Zarr

  • zarr, version 3.1.3 or newer.

    For reading and writing Zarr datasets.

Regridding

  • esmpy, previously named ESMF with the old module name also being accepted for import, version 8.7.0 or newer. This is easily installed via conda with

    $ conda install -c conda-forge "esmpy>=8.7.0"

    or may be installed from source.

Subspacing based on N-dimensional construct cells (N > 1) containing a given value

Active storage collapses

Tests

Tests are run from within the cf/test directory:

$ python run_tests.py

Code repository

The complete source code and issue tracker is available at https://github.com/NCAS-CMS/cf-python