Fix xESMF 'No module named ESMF' import error on conda-forge by upgrading to 0.7+ (esmpy over pyESMF)

Seeing ModuleNotFoundError: No module named ESMF after installing xESMF via conda-forge? Understand pyESMF vs esmpy and fix it fast by upgrading to xESMF 0.7+.

Installing xESMF via conda-forge can unexpectedly fail with an ESMF import error, even though the package itself seems to install successfully. The root of the issue lies in how older xESMF releases wire up their dependency on ESMF-related Python bindings. The good news: you don’t need to rebuild your entire environment to fix it.

Reproducing the problem

After installing xESMF with conda, a simple import triggers the failure:

import xesmf as xf

The error manifests as ModuleNotFoundError: No module named 'ESMF' and traces back through xESMF’s import chain: importing xesmf pulls in frontend.Regridder, which imports backend, which then tries import ESMF and crashes. ESMF itself is not available in the default conda channels or conda-forge, which is why the import cannot be satisfied.

What’s actually going on

The behavior depends on the xESMF version you’ve installed. Before 0.7, xESMF depended on pyESMF, which is not available via conda. Starting with 0.7, xESMF switched to esmpy and uses pyESMF only if esmpy is not available. This change ensures that the dependency chain can be resolved using conda-forge. If you are on a release older than 0.7, the package still attempts to import ESMF in a way that fails under conda-based setups.

The import logic in newer xESMF releases follows a pattern like this:

try:
    import esmpy as ESMF_lib
except ImportError:
    import ESMF as ESMF_lib

In other words, esmpy is preferred, and pyESMF is only used as a fallback. The relevant upstream change is documented in the project’s history.

Fix without rebuilding your environment

The most direct fix is to ensure your environment installs xESMF version 0.7 or higher. That release line uses esmpy first and only touches pyESMF if esmpy is not available. Install or upgrade with:

conda install -c conda-forge --override-channels "xesmf>=0.7"

After this, importing the package should work as expected:

import xesmf as xf

Why this matters

This is a clear example of how subtle dependency changes in upstream libraries can surface as import-time errors. Knowing which xESMF versions altered their dependency path from pyESMF to esmpy helps you avoid unnecessary environment rebuilds and integration retesting. Aligning with xESMF ≥ 0.7 restores a conda-friendly dependency chain and keeps your current stack intact.

Wrap-up

If you encounter ModuleNotFoundError: No module named 'ESMF' after installing xESMF, check the installed version. Upgrading to xESMF ≥ 0.7 resolves the issue by preferring esmpy, which fits cleanly into a conda-forge workflow. Use the command above to update in place, verify the import, and move on without re-creating your entire environment.