Installation

Cylc runs on Linux and macOS. We recommend installing it from conda-forge.

Quick Installation (for standalone machines)

Conda (recommended)

Use either conda, miniconda, mamba or micromamba:

conda install -c conda-forge cylc-flow

And optionally:

# install cylc-uiserver (provides the Cylc GUI)
conda install -c conda-forge cylc-uiserver

# install Rose support
conda install -c conda-forge cylc-rose metomi-rose

Pip

Use either pip or uv:

pip install cylc-flow

And optionally:

# install cylc-uiserver (provides the Cylc GUI)
pip install cylc-uiserver

# install Rose support
pip install cylc-rose metomi-rose

Once installed, you might want to configure:

Distributed Installation (for networks, HPC and cloud environments)

Cylc is a distributed system. Cylc schedulers can either submit jobs locally, or to external job runners such as PBS or Slurm.

With local job submission, it is sufficient to activate your Cylc environment and run the workflow [4]. However, when using external job runners or distributing schedulers over multiple nodes on a network, you will need a mechanism to intercept cylc commands and direct them to the environment where Cylc is installed (because environments do not persist with remote system calls and may not persist with job submission [1]).

To do this, we use a “wrapper script”, a simple shell script which you locate somewhere in the default $PATH.

What Are Wrapper Scripts?

A bare-bones wrapper script might look like this:

#!/bin/bash -l

# NOTE: intercept "cylc" calls and direct them to the
# "cylc-environment-name" conda environment
exec conda run -n cylc-environment-name cylc "$@"

Name this script cylc and insert it somewhere in $PATH and all cylc command calls will be routed via this environment without the need to manually activate it first.

Cylc provides a more advanced wrapper script which:

Supports multiple parallel deployments of Cylc at different versions [2].
Works with Conda, Mamba and Python virtual environments.
Doesn’t activate the environment (ensures background jobs submitted by Cylc consistently run in the system environment, not the Cylc environment [3]).

Setting Up The Cylc Wrapper Script

Extract the Cylc wrapper script to a directory within $PATH:

cylc get-resources cylc <directory>/cylc
chmod +x <directory>/cylc

Then edit the script and adjust CYLC_HOME_ROOT to the directory which contains your Cylc environment(s).

The wrapper script assumes your Cylc environments follow the naming pattern:

cylc-<version>
# OR
cylc-<version>-<arbitrary-id>

Note

Developers can set $CYLC_HOME_ROOT_ALT to point to their development environments. For example:

CYLC_HOME_ROOT_ALT=${HOME}/.conda/envs

You may wish to use the same approach for the isodatetime command, and, if using Rose for the rose and rosie commands.

To do so create a symbolic link to the wrapper, for each of these commands:

cd /path/to/directory  # the path where you installed the wrapper script
ln -s cylc rose
ln -s cylc rosie
ln -s cylc isodatetime

Further information on wrapper script functionality and interface can be found in the header of the script itself.

Cylc Packages

Cylc is split into a number of components providing different functionality:

Cylc Flow

Provides the scheduler “kernel” of Cylc along with the command line interface.

Cylc UI Server

Provides the “Cylc Hub” and the browser-based “Cylc GUI”.

Cylc Rose

Provides support for Rose suite configurations in Cylc workflows.

Rose

The Rose toolkit for writing, editing and running application configurations.

Installing On macOS

We recommend using the Homebrew package manager to install the Bash, coreutils and gnu-sed system dependencies:

$ brew install bash coreutils gnu-sed

You will need to prepend the coreutils and gnu-sed installations to your $PATH, follow the instructions in the brew install output.

Note

atrun (the at command) does not run out-of-the-box on macOS for security reasons and must be manually enabled if you want Cylc to submit jobs using at.

Note

The macOS default shell is zsh (not bash). You do not need to change this but be aware that Cylc uses bash (for job scripts) which has a subtly different syntax.

If you do not install bash (e.g, via Homebrew as mentioned above) you will get the ancient version Bash (3.2) that comes pre-installed with macOS.

Warning

SSH is disabled by default on macOS. It is required for distributed installations.

See the Apple support page for instructions on enabling SSH.

Configuration

Cylc uses “safe and sane” defaults and is suitable for use “out of the box”, if all you need to do is run jobs locally in the background. However, many things may need to be configured, e.g:

Platform Configuration (jobs hosts, runners, etc)
Scheduler Hosts
Default Event Handlers.

Cylc Flow

Cylc Flow is configured by the global.cylc file which supports configuration of the system on both a site and user basis.

The global.cylc file should be present on user machines (where users interact with Cylc on the command line) and on cylc servers (hosts where Cylc schedulers run). It is not required on job hosts.

More information about supported configuration items and defaults can be found: Global Configuration.

Cylc UI Server

The Cylc UI Server can be configured on a site and user basis. Guidance for configuration file storage, configuration variables and defaults can be found: UI Server Configuration.

Bash Profile

Cylc job scripts are bash scripts, which are good for manipulating files and processes. They invoke bash -l to allow environment configuration in login scripts.

Warning

Sites and users should ensure their bash login scripts configure the environment correctly for Cylc and do not write anything to stdout.

Shell Auto-Completion

Cylc provides auto-completion for the Bash shell which can save you typing:

Cylc commands
Workflow IDs
Cycle points
Task names

To extract the auto-completion file run the following command:

cylc get-resources cylc-completion.bash <path-to-copy-file>

Then follow the comments in the file to install it.

Text Editors

There is support for the .cylc file format in various text editors.

See syntax highlighting for more details.

Footnotes