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 initialize the controlled vocabularies:

esgvoc install

This command downloads ESGF project vocabularies from GitHub and builds local databases. Without this step, esgdrs and esgmapfile commands will fail with an error.

The installation downloads approximately 100MB of data and may take a few minutes depending on your connection.

IMPORTANT: Run esgvoc install 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.

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. Initialize the controlled vocabularies:

esgvoc install

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

# Initialize controlled vocabularies
uv run esgvoc install

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 install
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 >= 2.2.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.