{"id":7120,"library":"cwl-upgrader","title":"CWL Upgrader","description":"cwl-upgrader is a Python library and command-line tool designed to upgrade Common Workflow Language (CWL) documents. It supports upgrading CWL tools and workflows from older versions (draft-3, v1.0, v1.1) to the current v1.2 specification. The library focuses solely on syntax migration and does not perform validation of the document's correctness. It is actively maintained with frequent patch releases, often driven by dependency updates and Python version support.","status":"active","version":"1.2.15","language":"en","source_language":"en","source_url":"https://github.com/common-workflow-language/cwl-upgrader","tags":["CWL","workflow","upgrader","Common Workflow Language","CLI","schema"],"install":[{"cmd":"pip install cwl-upgrader","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Requires Python 3.10 or newer, dropping support for older versions in recent releases.","package":"python","version":">=3.10"},{"reason":"Core dependency for YAML parsing and manipulation.","package":"ruamel.yaml","version":">=0.16.0, <0.20"},{"reason":"Used internally for schema parsing and validation logic in the CWL ecosystem.","package":"schema-salad","version":">=8.8.20250205075315,<9"}],"imports":[{"note":"cwl-upgrader is primarily a command-line tool. Direct programmatic import of a public API for upgrading CWL documents is not the primary interface; users typically invoke the 'cwl-upgrader' executable.","symbol":"cwl-upgrader","correct":"cwl-upgrader --help"}],"quickstart":{"code":"# Create a sample CWL v1.0 CommandLineTool\ncat <<EOF > my_tool_v1_0.cwl\ncwlVersion: v1.0\nclass: CommandLineTool\nbaseCommand: echo\ninputs:\n  message:\n    type: string\n    inputBinding:\n      position: 1\noutputs:\n  output_file:\n    type: File\n    outputBinding:\n      glob: output.txt\nEOF\n\n# Upgrade the CWL document to v1.2\ncwl-upgrader my_tool_v1_0.cwl > my_tool_v1_2.cwl\n\n# Verify the upgraded file\ncat my_tool_v1_2.cwl","lang":"bash","description":"The cwl-upgrader tool is primarily used from the command line. This quickstart demonstrates how to create a simple CWL v1.0 `CommandLineTool` and then upgrade it to v1.2 using the `cwl-upgrader` executable. The output is redirected to a new file."},"warnings":[{"fix":"Upgrade your Python environment to 3.10, 3.11, 3.12, 3.13, or 3.14.","message":"Support for older Python versions has been progressively dropped. Ensure your environment uses Python 3.10 or newer.","severity":"breaking","affected_versions":">=1.2.9 (drops Python 3.6, 3.7); >=1.2.12 (drops Python 3.8); >=1.2.14 (drops Python 3.9)"},{"fix":"Run `cwltool --validate your_upgraded_document.cwl` after using `cwl-upgrader` to ensure the document is valid.","message":"cwl-upgrader performs syntax upgrades but does not validate the semantic correctness of the CWL document. Always validate your upgraded documents using a CWL reference implementation like `cwltool --validate` after upgrading.","severity":"gotcha","affected_versions":"All versions"},{"fix":"For 'sbg:draft-2' documents, use `pip install sevenbridges-cwl-draft2-upgrader` and then use the `sbg_cwl_upgrader` command.","message":"Documents written in the legacy 'sbg:draft-2' format are not supported by cwl-upgrader. A separate tool, `sevenbridges-cwl-draft2-upgrader`, is required for these older documents.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Review the CWL v1.2 specification changelog and adjust documents to conform to new requirements. Use `cwltool --validate` to pinpoint specific issues.","message":"CWL v1.2 introduces stricter rules and clarifications that might cause previously working (but non-standard) constructs to fail validation. For example, absolute paths starting with '/' for `InitialWorkDirRequirement` are only permitted in CWL 1.2 and later, and `loadContents` has a 64KiB size limit.","severity":"breaking","affected_versions":"All versions when upgrading to v1.2"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Ensure Python's script directory is in your PATH. If using a virtual environment, activate it (`source venv/bin/activate`). Reinstall with `pip install cwl-upgrader` to check for installation errors.","cause":"The `cwl-upgrader` executable is not in your system's PATH, or the installation failed, or the Python environment is not active.","error":"cwl-upgrader: command not found"},{"fix":"Verify the `cwlVersion` field in your input document. `cwl-upgrader` supports upgrading from draft-3, v1.0, and v1.1 to v1.2. If the document is already v1.2 or an unsupported version, no upgrade is necessary or possible with this tool.","cause":"The input CWL document specifies a `cwlVersion` that `cwl-upgrader` does not recognize as an upgradable source (e.g., already v1.2, or an unknown future version).","error":"Error: 'cwlVersion' must be one of 'v1.0', 'v1.1', 'v1.2'"},{"fix":"This is a post-upgrade validation error. Examine the specific line indicated in the error message. If using absolute paths in `InitialWorkDirRequirement`, ensure your target CWL `cwlVersion` is indeed `v1.2` and that the CWL runner you are using fully supports CWL v1.2 features. Consider adjusting paths to be relative if possible, or consult the CWL v1.2 specification for correct usage of such features.","cause":"This error typically occurs when a CWL document, even after upgrading to v1.2, uses features (like absolute paths in `InitialWorkDirRequirement`) that were not valid in previous versions and still cause issues with the CWL runner (like `cwltool`), or the document has not been correctly updated/validated.","error":"ERROR Workflow error, try again with --debug for more information: createfile.cwl:18:5: Name '/scripts/myscript.sh' at index 0 of listing is invalid, paths starting with '/' only permitted in CWL 1.2 and later."}]}