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:

1. Activate that environment.

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

3. 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:

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

2. 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

1. 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
   

2. Continue with the Use an Existing conda Installation instructions.

Build the uwtools Package Locally

1. Install the necessary build packages. If your conda’s base environment is not writable (e.g. you are using a shared conda installation), first create and activate your own environment, or follow the Use a Fresh Miniforge Installation instructions.

   conda install -y -c conda-forge --override-channels conda-build conda-verify
   

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

   cd /to/your/uwtools/clone
   make package
   

3. Verify local availability of the newly built package:

   conda search -c $CONDA_PREFIX/conda-bld --override-channels uwtools
   

4. Optionally, create an environment from the newly built package (specify the version if multiple local packages are available):

   conda create -y -n uwtools -c $CONDA_PREFIX/conda-bld -c conda-forge --override-channels uwtools[=<version>]