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

  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 from PyPI

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

  2. Install uwtools from PyPI:

    pip install unified-workflow-tools

    To install a specific version:

    pip install unified-workflow-tools==<version>

Note

ecFlow is not currently published to PyPI and so cannot be installed automatically as a dependency of uwtools, but the ecflow mode can still be used when ecFlow and its Python bindings are made available by other means. For example, they could be installed with conda, built from source, or made available by loading a system module. In any case, PATH must include the directory where ecflow_server and ecflow_client are installed, and PYTHONPATH must include the directory where the ecflow Python package is installed. These conditions are likely met if the commands which ecflow_server and python -c "import ecflow" succeed.

Execute with uvx

If you have uv installed, you can use its uvx tool to execute the uw CLI directly without explicit installation, e.g.:

$ uvx --from unified-workflow-tools uw config --help
usage: uw config [-h] [--version] ACTION ...

Handle configs

Optional arguments:
  -h, --help
      Show help and exit
  --version
      Show version info and exit

Positional arguments:
  ACTION
    compare
      Compare configs
    compose
      Compose configs
    realize
      Realize config
    validate
      Validate config

A specific version may be requested, e.g. uvx --from unified-workflow-tools==<version> uw config --help.

Note

Since uvx installs from PyPI, the ecFlow caveat described above applies: The ecflow mode can be used only if ecFlow and its Python bindings are made available by other means.