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?

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.