Install & Compatibility
Where this runs
tested against v0.42 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 0.962s · 55.8MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 5.5s · import 0.833s · 57MB
55MB installed
● package 55MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
load_document_by_uri
✓ from cwl_utils.parser import load_document_by_uri
Primary function to load a CWL document from a URI or file path.
save
✓ from cwl_utils.parser import save
Function to export a loaded CWL object into a built-in typed object.
This quickstart demonstrates how to programmatically load a CWL CommandLineTool document using `cwl-utils` from a local file. It creates a simple 'hello_world.cwl' file, loads it using `load_document_by_uri`, and then prints some attributes of the parsed CWL object. The example also includes cleanup for the created file.
from pathlib import Path
from cwl_utils.parser import load_document_by_uri
# Create a dummy CWL file for the example
cwl_content = """
cwlVersion: v1.2
class: CommandLineTool
baseCommand: echo
inputs:
message:
type: string
default: "Hello World from cwl-utils!"
inputBinding:
position: 1
outputs:
output:
type: stdout
"""
cwl_file_path = Path("hello_world.cwl")
cwl_file_path.write_text(cwl_content)
try:
# Load the CWL object from the file URI
# Note: For local files, str(Path_object) is often needed for older APIs
cwl_obj = load_document_by_uri(str(cwl_file_path))
print(f"Successfully loaded CWL Tool ID: {cwl_obj.id}")
print(f"CWL Version: {cwl_obj.cwlVersion}")
if hasattr(cwl_obj, 'inputs') and cwl_obj.inputs:
print(f"First input message default: {cwl_obj.inputs[0].default}")
except Exception as e:
print(f"An error occurred: {e}")
finally:
# Clean up the dummy file
if cwl_file_path.exists():
cwl_file_path.unlink()
cwl-utils --version
Errors
Common errors & fixes
ImportError: cannot import name 'load_document_by_uri' from 'cwl_utils.parser'
The `cwl_utils.parser` module or the specific function `load_document_by_uri` might not exist in an older installed version of `cwl-utils`, or the library is not installed correctly.
fixEnsure `cwl-utils` is installed: `pip install cwl-utils`. If already installed, try upgrading: `pip install --upgrade cwl-utils`. Verify correct import path from documentation.
schema_salad.exceptions.ValidationException: ... is not a valid CWL document.
The CWL file being loaded does not conform to the Common Workflow Language specification, or it uses a CWL version not fully supported by the installed `cwl-utils` version.
fixValidate your CWL document using `cwltool --validate your_workflow.cwl`. Consult the CWL specification for the version you are using. Ensure your `cwl-utils` is up-to-date for the CWL version.
yaml.scanner.ScannerError: while scanning for the next token Found character that cannot start any token
The CWL document (which is typically YAML) contains malformed syntax, such as incorrect indentation, invalid characters, or missing delimiters.
fixCarefully inspect the CWL YAML file for syntax errors, especially around the indicated line and column. Use a YAML linter or editor with YAML validation features.
AttributeError: 'NoneType' object has no attribute 'id'
`load_document_by_uri` or a similar parsing function returned `None`, likely because the specified file path was incorrect, the file was empty, or an internal parsing error occurred without raising a more specific exception.
fixCheck if the file path passed to `load_document_by_uri` is correct and accessible. Ensure the CWL file is not empty and contains valid CWL content. Add checks for `None` return values after loading.
Upgrade
Version history
0.42latest on PyPI · released Jun 1, 2026
Audit
Dependencies
pythonrequiredRequires Python <3.15, >=3.10 as of version 0.41.
schema-saladrequiredCore dependency for schema parsing and code generation. Version requirements can change between cwl-utils releases.
ruamel.yamlrequiredUsed for YAML parsing of CWL documents.