Install Guide

This page is for installing Sophios as a package. It focuses on two things:

  • installing the Python package with pip,

  • installing the non-Python tools that local workflow execution may need.

If you want to edit Sophios itself, run the test suite, build the documentation, or use the repository examples directly from a checkout, use the Developer Install Guide instead.

Python Requirement

Sophios declares its supported Python range in pyproject.toml. For the current package, use Python 3.11 or newer.

Check your interpreter:

python --version

If your system Python is older, create an environment with a newer Python before installing Sophios.

Install Sophios

Using a virtual environment is recommended:

python -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install sophios

On Windows PowerShell, activate the virtual environment with:

.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install sophios

Verify the command-line entry point:

sophios --help

Verify the public Python APIs:

python - <<'PY'
from sophios.apis.python.workflow import Step, Workflow
from sophios.apis.python.tool_builder import CommandLineTool, Input, Output, cwl
from sophios.compute_payload import ComputeWorkflowPayload

print("Sophios is installed")
PY

What pip install sophios Provides

The sophios package installs the Python libraries needed for authoring, compiling, validating, and running workflows through the supported Python APIs and CLI.

That includes the Python packages for:

  • CWL compilation and local runner integration,

  • .wic YAML parsing and validation,

  • Python workflow authoring with Step and Workflow,

  • Python tool authoring with CommandLineTool,

  • compute payload construction and validation.

pip does not install every system executable that a workflow may call. The next section covers those tools.

Install Non-Python Runtime Tools

The exact tools you need depend on the workflows you run.

Container Runtime

Install Docker or Podman when workflows use containerized CWL tools.

Sophios can author and compile workflows without Docker or Podman, but local execution of containerized tools requires a working container runtime.

Check one of:

docker --version
podman --version

For Docker, Docker Desktop is the usual path on macOS and Windows. On Linux, install Docker or Podman through your distribution package manager.

Node.js

Install Node.js when workflows use CWL JavaScript expressions such as InlineJavascriptRequirement.

Check:

node --version

Install examples:

conda install -c conda-forge nodejs

brew install node

sudo apt-get update
sudo apt-get install -y nodejs

Graphviz

Install the Graphviz system package when you want rendered workflow diagrams. The Python graphviz package installed by pip is only the Python binding; the dot executable is a separate system dependency.

Check:

dot -V

Install examples:

conda install -c conda-forge graphviz

brew install graphviz

sudo apt-get update
sudo apt-get install -y graphviz

Tools Invoked by Your Workflow

Sophios describes workflows. It does not install every command-line program that your workflow might invoke.

For example, if your CWL tool runs samtools, python, bash, or a project specific executable outside a container, that executable must be available in the runtime environment.

Quick Environment Check

This check reports the optional system tools Sophios commonly uses:

python - <<'PY'
import shutil

checks = {
    "node": "needed for CWL JavaScript expressions",
    "dot": "needed for Graphviz diagrams",
    "docker": "needed for Docker-backed local execution",
    "podman": "needed for Podman-backed local execution",
}

for executable, reason in checks.items():
    path = shutil.which(executable)
    status = path if path else "not found"
    print(f"{executable:>6}: {status} ({reason})")
PY

Missing optional tools are not always errors. Install the tools required by the workflows you plan to run.

Next Steps

After installation, start with the Python Workflow API. If you need standalone .wic workflows or YAML editor validation, see Advanced YAML and Operations.