Installation

Note

Developers should visit the Developer Setup section located in the Contributor Guide.

The recommended installation mechanism uses the Python package and virtual-environment manager conda. The Miniforge variant of Miniconda, which by default uses packages from the conda-forge project, is an especially useful basis for working with conda.

Use an Existing conda Installation

Install Into an Existing Environment

To install uwtools into an existing environment in an existing conda (e.g., Miniforge, Miniconda, Anaconda) installation:

Activate that environment.
Identify the uwtools version number to install from the available versions shown by conda search -c ufs-community --override-channels uwtools.

Install uwtools into the active environment:

conda install -c ufs-community -c conda-forge --override-channels uwtools=<version>

Create a Standalone `uwtools` Environment

To create a standalone conda environment providing uwtools:

Identify the uwtools version number to install from the available versions shown by conda search -c ufs-community --override-channels uwtools.

Create the environment (here named uwtools via the -n flag, but any name may be used):

conda create -n uwtools -c ufs-community -c conda-forge --override-channels uwtools=<version>

Use a Fresh Miniforge Installation

Visit the Miniforge releases page and obtain the URL and filename for the Miniforge3-[os]-[architecture].sh installer appropriate to your system, for example Miniforge3-Linux-x86_64.sh or Miniforge3-MacOSX-arm64.sh. Download, install, and activate. Modify the $HOME/conda installation directory per your needs.
```
wget <URL>
bash <filename> -bfp $HOME/conda
rm <filename>
source $HOME/conda/etc/profile.d/conda.sh
conda activate
```
After initial installation, this conda may be activated at any time with the command:
```
source $HOME/conda/etc/profile.d/conda.sh && conda activate
```
Continue with the Use an Existing conda Installation instructions.

Build the `uwtools` Package Locally

Install the necessary build packages into the conda installation’s base environment (see the Use a Fresh Miniforge Installation instructions if an installation is unavailable or not writable):
```
conda install -c conda-forge --override-channels conda-build conda-verify
```

In a clone of the uwtools repository, build the uwtools package:

cd /to/your/uwtools/clone
conda build recipe -c conda-forge --override-channels

Verify local availability of the newly built package:
```
conda search -c local --override-channels uwtools
```
Optionally, create an environment from the newly built package (specify the version if multiple local packages are available):
```
conda create -n uwtools -c local -c conda-forge --override-channels uwtools[=<version>]
```