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. Specifically, these instructions assume use of the Miniforge variant of Miniconda, built to use, by default, packages from the conda-forge project. Users of the original Miniconda or the Anaconda distribution should add the flags -c conda-forge --override-channels to conda commands to specify the required package channels.

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 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 uwtools=<version>
```

Use a Fresh Miniforge Installation

If no existing conda installation is available, install Miniforge.

This recipe uses the aarch64 (64-bit ARM) Miniforge for Linux and installs into $HOME/conda. Adjust as necessary for the target system.

Download, install, and activate the latest Miniforge for the target system.

wget https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-Linux-aarch64.sh
bash Miniforge3-Linux-aarch64.sh -bfp ~/conda
rm Miniforge3-Linux-aarch64.sh
source ~/conda/etc/profile.d/conda.sh
conda activate

After initial installation, this conda may be activated with the command:

source ~/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 conda-build conda-verify
```
In a clone of the uwtools repository, build the uwtools package:
```
cd /to/your/uwtools/clone
conda build recipe
```

Verify local availability of the newly built package:

conda search -c local --override-channels uwtools  # do not add -c conda-forge to this command

Optionally, create an environment from the newly built package:

conda create -n uwtools -c local uwtools[=<version>]  # specify version if multiple choices are available