Installation

nwp-compose installs entirely in user space. There is no system package, no service, and no elevated step. If you can git clone and write to a directory, you can install it.

Prerequisites

• Python 3.12+ — required by the pinned cylc-flow (8.6.4). 3.12 is the floor; newer minors work.
• git and a POSIX shell (bash/zsh). macOS and Linux are first-class; Windows users should use WSL.

No compiler, no root, no Docker daemon.

Install

1. Clone and run the idempotent setup script:

   git clone https://github.com/NCAR/nwp-compose.git
   cd nwp-compose
   ./setup.sh

   setup.sh creates a .venv/, installs the pinned cylc-flow==8.6.4, and runs pip install -e . so the nwp-compose console script is available on PATH inside the venv.

2. Activate the environment:

   source .venv/bin/activate

3. Confirm:

   cylc --version          # → 8.6.4
   nwp-compose --help       # → the CLI surface
   nwp-compose doctor       # → preflight: is this node ready to run?

Installing from NCAR Nexus (internal)

NCAR users on-network can pip install nwp-compose from the internal Nexus package index instead of cloning — useful for dropping the tool into an existing environment. This is the internal distribution channel while the project is pre-release; it is NCAR-network only (VPN off-site) and unreachable from cloud clusters (e.g. AWS ParallelCluster), where you should use the git-clone + setup.sh path above.

1. Store your Nexus password once (needs the keyring package):

   pip install keyring
   keyring set http://nexus.rap.ucar.edu:8081 "$USER"

2. Point pip at the Nexus PyPI group in ~/.config/pip/pip.conf:

   [global]
   extra-index-url = http://<user>@nexus.rap.ucar.edu:8081/repository/pypi-all/simple
   trusted-host = nexus.rap.ucar.edu
   timeout = 2
   
   [auth]
   keyring-provider = keyring

3. Install into your activated environment:

   pip install nwp-compose

   The pypi-all group proxies public PyPI too, so this pulls cylc-flow and every other dependency in one resolve. You still need a Cylc-capable environment to run workflows — pip install nwp-compose gives you the CLI and the engine, but the model binaries (MPAS/WRF) are staged separately on your cluster.

Shared-filesystem and quota overrides

On HPC login nodes, $HOME is often small or on slow NFS, and a Cylc virtual environment is 200–400 MB. nwp-compose honors environment overrides so state never has to live where it would bust a quota. Set these before setup.sh / your first run:

Override	Redirects	Default
NWPC_VENV_DIR	the .venv/ location	<repo>/.venv
XDG_CACHE_HOME	the gist/HTTP cache	~/.cache/nwp-compose
XDG_DATA_HOME	the plugin component dir	~/.local/share/nwp-compose
CYLC_RUN_DIR	where Cylc writes run dirs	~/cylc-run

# Example: keep everything on scratch, off a quota-limited home
export NWPC_VENV_DIR=/scratch/$USER/nwpc/venv
export XDG_CACHE_HOME=/scratch/$USER/.cache
export CYLC_RUN_DIR=/scratch/$USER/cylc-run
./setup.sh

Let doctor tell you

nwp-compose doctor probes each of these — Python and Cylc versions, venv health, write access and free space on ~/cylc-run and the cache, GUI port availability, and per-component prerequisite executables — and prints the exact override to set when something is red. Run it once on a new node before your first forecast. See The last mile.

Why Cylc is pinned

cylc-flow==8.6.4 is pinned for reproducibility. Newer 8.x versions are likely fine, but Cylc has had behavioral shifts between minors, so bumping the pin is a reviewed change, not an automatic upgrade. (Jinja2 is correspondingly pinned <3.2 to match Cylc’s own constraint.)

Next

• Quick start — generate and run a forecast in five commands.
• Tutorial: your first forecast — the guided version.