Installation¶

Prerequisites¶

Python 3.10 through 3.13 - Groundhog temporarily does not support Python 3.14+ due to an upstream incompatibility in the Globus Compute SDK. This will be resolved in a future release.
Access to a Globus Compute endpoint - You'll need access to an HPC cluster or remote compute resource running a Globus Compute endpoint. If you don't have one configured, see the Globus Compute documentation for setup instructions.

Installing with uv (recommended)¶

The recommended way to install Groundhog is using uv's tool management:

uv tool install --python 3.13 groundhog-hpc@latest

This installs the hog CLI in an isolated environment with Python 3.13, keeping your system Python clean.

Python version requirement

The --python 3.13 flag is important: uv tool install defaults to the latest Python version available, which may be 3.14+. Groundhog temporarily requires Python 3.13 or earlier due to an upstream dependency issue that will be resolved in a future release.

Verifying installation¶

Check that the installation succeeded:

hog --version

Upgrading¶

To upgrade to the latest version:

uv tool upgrade groundhog-hpc

Adding packages to the tool environment¶

If you need to add additional packages to Groundhog's tool environment (for example, if you need certain modules present in order to deserialize results):

uv tool install groundhog-hpc --with some-package

To add packages to an existing installation:

uv tool install --reinstall groundhog-hpc --with some-package

Alternative: Installing with pip¶

You can also install with pip, though this is not recommended for most users:

pip install groundhog-hpc

Warning

Installing with pip into your global Python environment can cause dependency conflicts. Consider using a virtual environment or the uv tool installation method instead.

Installing from source¶

For development or to use the latest unreleased features:

git clone https://github.com/Garden-AI/groundhog.git
cd groundhog
uv tool install .

Next steps¶

Once installed, continue to the Quickstart to write your first groundhog function.