Clay Foundation Model: an open source Earth observation model you can pip install

A model and its interface shipped together

Earth observation work has a recurring shape: you have satellite imagery, you want a representation of it that a downstream model or an analyst can use, and you do not want to spend a week assembling a data pipeline and a training loop. The Clay Foundation Model targets that gap with two things in one repository, an AI model and an interface for Earth.

The topic tags say what the inputs look like: earth-observation, satellite-imagery, digital-elevation-model, embeddings, sentinel-1 and sentinel-2. So the model sits in the geospatial embedding space, and the package is aimed at people who already have imagery and need a useful representation out of it.

The licensing is unusually clean for this kind of release. The documentation states that Clay Model is licensed under Apache, and that this applies to the source code as well as the trained model weights. The documentation itself is CC-BY-4.0. That combination matters more than it sounds: a foundation model whose weights carry a restrictive licence is often unusable commercially, so shipping the weights under the same permissive licence as the code removes a whole category of friction. The pyproject.toml classifiers agree, listing the Apache Software License and the intended audience as Science/Research.

The claymodel package and what it actually pulls in

The pip-installable distribution is named claymodel, and the project metadata gives version 1.5.0 with a description of an open source AI model and interface for Earth observation. The import names follow directly: a datamodule entry point and a module entry point, which is the shape Lightning-based projects use.

from claymodel.datamodule import ClayDataModule
from claymodel.module import ClayMAEModule

The dependency list tells you the technical shape of the model. torch at 2.4.0 or newer and torchvision at 0.19.0 or newer are the base, einops pins the tensor layout work, timm at 0.6.0 or newer and vit-pytorch supply the vision transformer backbone family, lightning at 2.0.0 or newer handles the training loop, and jsonargparse with signatures handles the configuration layer. Then there is the geospatial and analysis stack: geopandas, scikit-learn, scikit-image, matplotlib and python-box, with wandb for experiment tracking.

Two practical consequences. First, this is a heavy install: torch plus a vision stack plus geospatial libraries is a large download and a large disk footprint, so a container or a prebuilt environment is the sane starting point. Second, requires-python is 3.11 or newer, which is a floor that will exclude older LTS system Python versions outright.

pip install from git, or a mamba environment for development

The recommended route for users is pip straight from the repository, and the README notes that this installs the claymodel package and all its dependencies.

    pip install git+https://github.com/Clay-foundation/model.git

There is a second path for development and advanced usage, and it is not merely a variant of the first. The instructions are to clone the repository, then use mamba to install the dependencies, which creates a virtual environment with Python and JupyterLab included. The command has been tested on Linux devices with CUDA GPUs, which is a strong hint about where this is expected to run.

    git clone <repo-url>
    cd model

    mamba env create --file environment.yml

    mamba activate claymodel

After activation, mamba list confirms the libraries are present. The environment.yml file at the repository root is the single source for that environment. Choosing the mamba route over pip is a real decision rather than a stylistic one: mamba resolves the dependency tree with conda, which handles the binary-heavy scientific stack differently from pip, and the environment file also pins the CUDA-enabled builds that a plain pip install may not pick.

Running the trainer through LightningCLI

The model is run through LightningCLI v2, and the trainer script is the entry point. Checking the available options and the hyperparameter configurations comes first.

    python trainer.py --help

The quick check runs a single batch of the validation set, which is the fastest way to find out whether data loading, configuration and model wiring actually work together.

    python trainer.py fit --model ClayMAEModule --data ClayDataModule --config configs/config.yaml --trainer.fast_dev_run=True

Training for real is the same command without the fast_dev_run flag.

    python trainer.py fit --model ClayMAEModule --data ClayDataModule --config configs/config.yaml

Two constraints here deserve attention. The configuration lives at configs/config.yaml in the repository, and the README explicitly warns that if you installed via pip you will need to clone the repository to access the trainer script and config files. So the pip install gives you the library while the trainer path requires the source tree, which means a pip-only deployment can consume the model but not retrain it through the documented script. The model, data and config are wired together by name on the command line, so the whole configuration surface is visible in one invocation, and more options are available through the fit help output.

JupyterLab for the notebooks, and how the docs get built

The quickstart path leads into a JupyterLab environment rather than a script, with Binder and SageMaker Studio Lab offered as launch points. The local equivalent requires a kernel to be registered first, then JupyterLab started in the background.

    mamba activate claymodel
    python -m ipykernel install --user --name claymodel  # to install virtual env properly
    jupyter kernelspec list --json                       # see if kernel is installed
    jupyter lab &

The kernelspec check exists because a missing kernel is the usual reason a notebook appears with the wrong interpreter. The documentation itself is a Jupyter Book, and building it needs the book tool installed with a pip install of jupyter-book, then a build of the docs directory. Previewing the result locally means serving the built HTML directory with the standard library module.

jupyter-book build docs/

python -m http.server --directory _build/html

Deployment is automated by a GitHub Action on .github/workflows/deploy-docs.yml that builds the site and pushes it to GitHub Pages, so the docs are versioned alongside the code rather than being maintained as a separate site.

Repository layout and the gap between tags and metadata

The tree shows a working research project rather than a thin wrapper. claymodel/ holds the package itself, configs/ holds the training configuration, cluster/ holds cluster launch material, utils/ holds helper scripts, and there is a copy_data.sh script at the root for pulling data locally, plus train_clay.sh as a wrapper. docs/ holds the Jupyter Book sources. Configuration for the toolchain lives in pyproject.toml, environment.yml, ruff.toml and .ruff.toml, with a pre-commit config for the hooks.

Here is the detail worth pausing on. The tagged releases are v1.0.1 on 2025-07-05, v1.0 on 2024-06-06 and v0.0.1 on 2024-01-12, with the v1.0.1 release described as pip installable. The pyproject.toml, however, declares version 1.5.0. That gap between the tagged releases and the package version is the kind of thing that bites when you pin a dependency: if you write claymodel==1.0.1 you get a version considerably behind what the source tree describes, and if you install from git you get 1.5.0 regardless of the tags.

The last push was on 2026-05-11. The release tags are older than that, which tells you the branch has moved on since the last tag, and it is the state of the default branch that anyone installing from git receives today.

Where the Clay Foundation Model stops being the right tool

There are three honest limits. The first is hardware and environment. The documented test environment is Linux with CUDA GPUs, and the dependency stack is deep enough that a CPU-only environment is possible but not what the project describes. If your pipeline has to run on a laptop without a GPU, this is a heavy thing to install.

The second is the retraining path. The README is explicit that a pip install gives you the package but not the trainer script or the config files, so anyone who installed from pip and then wants to fine-tune on their own imagery has to clone the repository anyway. The pip path is an inference path, not a training path, and treating it as a training shortcut will end at the missing configs/config.yaml file.

The third is the scope of the licence, not its permissiveness. Apache-2.0 covers the code and the weights, and CC-BY-4.0 covers the documentation, which is convenient for redistribution. What that licence does not give you is a guarantee that the model suits your sensors, your resolution or your downstream task. Nothing in the documented interface describes which outputs the embeddings are validated against, so the sensible move for an evaluation is to build the environment, run the fast_dev_run configuration on your own data and look at the result before wiring it into a pipeline.

Editorial conclusion

Adopt the Clay Foundation Model if you need a pretrained geospatial representation for Sentinel-1 and Sentinel-2 style data and want the weights and the training code under one Apache-2.0 licence, and skip it if you need a task-specific model for a single narrow use case. Before building on it, check that the version in pyproject.toml, 1.5.0, matches the tagged release you intend to pin, since the tags are older than the package version, and confirm Python 3.11 or newer and a CUDA GPU are available in the environment you plan to run in.

Frequently asked questions

Official sources

1. Clay-foundation/model on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases