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>]
   

Install uwtools into a non-conda environment

If you are using an app that has its own environment requirements that do not work well with conda, you may need to install with pip instead.

1. Clone the uwtools repo and check out the desired release tag.

   git clone https://github.com/ufs-community/uwtools.git
   cd uwtools
   git checkout <tag>
   

2. Optional but recommended: Create and activate a Python virtual environment, to avoid installing into the base Python installation.

   python -m venv uwtools-venv
   . uwtools-venv/bin/activate
   

3. Install uwtools and its required dependencies from the src/ directory:

   cd src/
   pip install .