Installation

Note

esgprep version 3.0+ requires Python 3.12 or higher.

Installation from PyPI

pip install esgprep

Important

REQUIRED: After installing esgprep, you must activate the controlled vocabulary databases for each project you need:

esgvoc use cmip6@latest
esgvoc use cordex-cmip6@latest

This command downloads pre-built vocabulary databases for the specified project. Without this step, esgdrs and esgmapfile commands will fail with an error.

IMPORTANT: Run esgvoc use <project>@latest periodically to update your local vocabularies with the latest controlled vocabulary changes from ESGF projects. Outdated vocabularies may cause validation errors or prevent recognition of newly added facets, experiments, or models.

To see available projects and installed versions:

esgvoc status

For more information about controlled vocabularies management, see the esgvoc documentation.

Installation from GitHub

1. Clone our GitHub project:

git clone https://github.com/ESGF/esgf-prepare.git
cd esgf-prepare

2. Install using pip:

pip install -e .

3. Activate the controlled vocabulary databases for your projects:

esgvoc use cmip6@latest

4. The esgdrs and esgmapfile command-lines are now available.

Using uv (recommended)

For a faster and more modern Python package manager, you can use uv:

# Install uv if not already installed
curl -LsSf https://astral.sh/uv/install.sh | sh

# Create a virtual environment and install esgprep
uv sync

# Activate controlled vocabulary databases
uv run esgvoc use cmip6@latest

Tip

Activate the virtual environment to avoid prefixing every command with uv run:

# Activate the virtual environment created by uv
source .venv/bin/activate

# Now all commands work directly
esgvoc use cmip6@latest
esgdrs --version
esgmapfile --version

# Deactivate when done
deactivate

Once activated, all commands in this documentation can be used without the uv run prefix.

Warning

To run esgprep tools you have to be logged into a machine which mounts the filesystem hosting the data to publish.

Dependencies and requirements

System requirements:

• Linux distribution

• Python 3.12 or higher

Python dependencies:

esgprep uses standard Python libraries and the following external packages:

• esgvoc >= 4.1.1 - ESGF controlled vocabulary and configuration handler (replaces ESGConfigParser)

• fuzzywuzzy >= 0.18.0 - Fuzzy string matching

• hurry.filesize >= 0.9 - Human-readable file sizes

• lockfile >= 0.12.2 - File locking

• netCDF4 >= 1.7.2 - NetCDF file handling

• numpy >= 2.2.6 - Numerical computing

• python-levenshtein >= 0.27.1 - Fast string matching

• requests >= 2.32.3 - HTTP library

• treelib >= 1.7.1 - Tree data structure

All dependencies are automatically installed when installing esgprep via pip.