Installation

Try on Binder without local installation

The Binder project provides pre-configured environment in the cloud. You just need a web browser to access it. Please follow the Binder link on xESMF’s GitHub page.

Install on local machine with Conda

xESMF requires Python>=3.6. The major dependencies are xarray and ESMPy. The best way to install them is using Conda.

First, install miniconda. Then, we recommend creating a new, clean environment:

$ conda create -n xesmf_env python=3.7
$ conda activate xesmf_env

Getting xESMF is as simple as:

$ conda install -c conda-forge xesmf

Warning

One some platforms you might get ImportError: Regrid(filename) requires PIO and does not work if ESMF has not been built with MPI support. (see this comment). A quick workaround is to constrain ESMPy version conda install -c conda-forge xesmf esmpy=8.0.0.

We also highly recommend those extra packages for full functionality:

# to support all features in xESMF
$ conda install -c conda-forge dask netCDF4

# optional dependencies for executing all notebook examples
$ conda install -c conda-forge matplotlib cartopy jupyterlab

Alternatively, you can first install dependencies, and then use pip to install xESMF:

$ conda install -c conda-forge esmpy xarray scipy dask netCDF4
$ pip install git+https://github.com/pangeo-data/xesmf.git

This will install the latest version from the github repo. To install a specific release, append the version tag to the url (e.g. @v0.5.0). Note that pip install xesmf can only be used to install versions up to 0.3.0.

Testing your installation

xESMF itself is a lightweight package, but its dependency ESMPy is a quite heavy and sometimes might be installed incorrectly. To validate & debug your installation, you can use pytest to run the test suites:

$ pip install pytest
$ pytest -v --pyargs xesmf  # should all pass

A common cause of error (especially for HPC cluster users) is that pre-installed modules like NetCDF, MPI, and ESMF are incompatible with the conda-installed equivalents. Make sure you have a clean environment when running conda install (do not module load other libraries). See this issue for more discussions.

Notes for Windows users

The ESMPy conda package is currently only available for Linux and Mac OSX. Windows users can try the Linux subsystem or docker-miniconda .

Installing scientific software on Windows can often be a pain, and Docker is a pretty good workaround. It takes some time to learn but worths the effort. Check out this tutorial on using Docker with Anaconda.

This problem is being investigated. See this other issue.

Install development version from GitHub repo

To get the latest version that is not uploaded to PyPI yet:

$ pip install --upgrade git+https://github.com/pangeo-data/xESMF.git

Developers can track source code change:

$ git clone https://github.com/pangeo-data/xESMF.git
$ cd xESMF
$ pip install -e .