{"id":6579,"library":"cwltool","title":"cwltool","description":"cwltool is the reference implementation for the Common Workflow Language (CWL), enabling users to parse, validate, and execute CWL workflows and command-line tools. It supports various execution environments, including Docker and Singularity. The current version is 3.2.20260411152607, and it maintains a rapid, date-based release cadence, with version numbers reflecting both CWL specification and release date.","status":"active","version":"3.2.20260411152607","language":"en","source_language":"en","source_url":"https://github.com/common-workflow-language/cwltool","tags":["workflow-engine","cwl","bioinformatics","cli-tool","workflow"],"install":[{"cmd":"pip install cwltool","lang":"bash","label":"Install cwltool"}],"dependencies":[],"imports":[{"note":"Primary entry point for CLI-like execution.","symbol":"main","correct":"from cwltool.main import main"},{"note":"Use `load_tool` to correctly parse and validate CWL documents (workflows or tools) into their respective Python objects (`Workflow`, `CommandLineTool`). Directly importing and instantiating process classes from internal modules is generally not the recommended way to load CWL definitions.","wrong":"from cwltool.workflow import Workflow # Or from cwltool.process import CommandLineTool","symbol":"load_tool","correct":"from cwltool.load_tool import load_tool"},{"note":"Used for configuring the loading environment, including base URIs and schema definitions.","symbol":"LoadingContext","correct":"from cwltool.context import LoadingContext"}],"quickstart":{"code":"import os\nfrom cwltool.load_tool import load_tool\nfrom cwltool.context import LoadingContext\n\n# 1. Define a simple CWL CommandLineTool\ncwl_content = \"\"\"\ncwlVersion: v1.0\nclass: CommandLineTool\nid: my_echo_tool\nbaseCommand: echo\ninputs:\n  message:\n    type: string\n    inputBinding:\n      position: 1\noutputs:\n  output_message:\n    type: stdout\nstdout: output.txt\n\"\"\"\n\n# 2. Save it to a temporary file\ncwl_file_path = \"simple_echo.cwl\"\nwith open(cwl_file_path, \"w\") as f:\n    f.write(cwl_content)\n\ntry:\n    # 3. Load and validate the CWL document\n    # A LoadingContext is often required for proper resolution of includes/imports\n    # and setting the base URI.\n    loadingContext = LoadingContext({\"$base\": os.path.abspath(os.path.dirname(cwl_file_path))})\n    loadingContext.fileuri = f\"file://{os.path.abspath(cwl_file_path)}\"\n    \n    # load_tool returns a Process object (CommandLineTool, Workflow, or ExpressionTool)\n    tool = load_tool(cwl_file_path, loadingContext)\n\n    print(f\"Successfully loaded and validated CWL tool: {tool.tool_id}\")\n    print(f\"Tool class: {tool.class_}\")\n    print(f\"Inputs: {[i.id for i in tool.inputs]}\")\n    print(f\"Outputs: {[o.id for o in tool.outputs]}\")\n\n    # To actually *run* it, you would typically use cwltool.main.main\n    # or a custom executor with an input object.\n    # The `load_tool` function is primarily for parsing and validation.\n\nexcept Exception as e:\n    print(f\"Error loading CWL tool: {e}\")\nfinally:\n    # Clean up the temporary file\n    if os.path.exists(cwl_file_path):\n        os.remove(cwl_file_path)\n","lang":"python","description":"This quickstart demonstrates how to programmatically load and validate a Common Workflow Language (CWL) CommandLineTool definition using `cwltool.load_tool`. This is the primary method for parsing CWL documents into Python objects for inspection or further processing."},"warnings":[{"fix":"Upgrade Python to version 3.10 or later.","message":"Python 3.9 support was dropped in `cwltool` version 3.1.20260108082145. Earlier, Python 3.8 support was removed in 3.1.20241024121129. Users must ensure their environment uses Python 3.10 or newer.","severity":"breaking","affected_versions":"<3.1.20260108082145"},{"fix":"For parsing and validation, use `cwltool.load_tool`. For execution, consider wrapping `cwltool.main.main` with appropriate arguments, or consult advanced documentation on `cwltool.executors` for fine-grained control.","message":"Programmatic execution of CWL workflows/tools with `cwltool` can be complex, often requiring the use of `cwltool.main.main` (mimicking CLI calls) or setting up specific `Executor` and `LoadingContext` objects. Directly instantiating `Process` objects (like `CommandLineTool` or `Workflow`) from internal modules is not the recommended or simplest path for execution.","severity":"gotcha","affected_versions":"All"},{"fix":"Refer to the release notes and documentation for specific API changes. The `MAJOR.MINOR` segment is generally stable in terms of CWL spec compatibility, indicating the supported CWL version.","message":"The `cwltool` versioning scheme follows a `MAJOR.MINOR.DATE` pattern (e.g., `3.2.20260411152607`). The `MAJOR.MINOR` part typically corresponds to the supported CWL specification version (e.g., `3.2` implies CWL v1.2), while the date reflects the release date. This can sometimes be confusing when tracking API changes independently of CWL specification changes.","severity":"gotcha","affected_versions":"All"},{"fix":"Ensure Docker, Singularity, or another supported container engine is installed, running, and properly configured (e.g., user added to `docker` group). Verify container images can be pulled and run independently of `cwltool`.","message":"`cwltool` heavily relies on external container runtimes (like Docker, Singularity/Apptainer, Podman) for executing containerized tools and workflows. Issues with container daemon availability, permissions, or image pulling are common troubleshooting points.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-15T00:00:00.000Z","next_check":"2026-07-14T00:00:00.000Z","problems":[]}