{"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":"python","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,"search_vec":"'3.2.20260411152607':40 'base':48 'bioinformat':65 'cadenc':50 'cli':67 'cli-tool':66 'command':24 'command-lin':23 'common':9 'current':37 'cwl':12,20,56,64 'cwltool':1,2 'date':47,60 'date-bas':46 'docker':33 'enabl':13 'engin':63 'environ':31 'execut':19,30 'implement':6 'includ':32 'languag':11 'line':25 'maintain':43 'number':53 'pars':16 'rapid':45 'refer':5 'reflect':54 'releas':49,59 'singular':35 'specif':57 'support':28 'tool':26,68 'user':14 'valid':17 'various':29 'version':38,52 'workflow':10,21,62,69 'workflow-engin':61","created_at":"2026-04-15T18:33:57.976687+00:00","updated_at":"2026-04-16T04:39:15.652999+00:00","problems":[{"fix":"Install the cwltool package using pip: `pip install cwltool`","cause":"The `cwltool` package is not installed in the Python environment, or the Python interpreter cannot find it.","error":"ModuleNotFoundError: No module named 'cwltool'"},{"fix":"Correct the syntax of the parameter reference in the CWL expression or add `InlineJavascriptRequirement: {}` to the `requirements` section of your CWL document if you are using JavaScript expressions. Ensure identifiers (like `sample-input`) are valid in JavaScript if used in expressions (hyphens can cause issues, use `inputs['sample-input']` or rename the input).","cause":"There is a syntax error in a CWL expression, often related to how input parameters are referenced, or JavaScript code is used without explicitly declaring the `InlineJavascriptRequirement` in the CWL document.","error":"Workflow error, try again with --debug for more information: ... Expression evaluation error: Syntax error in parameter reference '(inputs. sample-input)'. This could be due to using Javascript code without specifying InlineJavascriptRequirement."},{"fix":"Run `cwltool --validate your_workflow.cwl` to get detailed validation errors. Review the reported issues and correct the CWL syntax, schema, or structural problems in your workflow definition. Ensure all required fields are present and correctly typed.","cause":"The CWL workflow or tool definition file contains errors that prevent it from conforming to the Common Workflow Language specification.","error":"Workflow failed validation"},{"fix":"Ensure Docker is running and properly configured on your system. Verify your internet connection. Check the Docker image name and tag in your CWL file for typos. If it's a private repository, ensure you are logged in to Docker. You can also try pulling the image manually with `docker pull <image_name>`.","cause":"cwltool could not pull the specified Docker image, possibly due to Docker not running, network issues, or incorrect image name/tag.","error":"could not run docker pull"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"3.2.20260413085819","cli_name":"cwltool","cli_version":"/usr/local/bin/cwltool 3.2.20260413085819","type":"library","homepage":null,"github":"https://github.com/common-workflow-language/cwltool","docs":null,"changelog":null,"pypi":"https://pypi.org/project/cwltool/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["workflow"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-06-28","next_check":"2026-07-28","install_tag":null}}