Try on Binder without local installation¶
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
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¶
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 .