{"id":9114,"library":"miniwdl","title":"miniwdl","description":"miniwdl is a Python library and command-line tool for running and developing Workflow Description Language (WDL) workflows locally. It provides a WDL runtime, a parser, and utilities for WDL authors. The current version is 1.13.1, and it maintains an active release cadence, addressing bugs, updating dependencies, and enhancing WDL specification compliance.","status":"active","version":"1.13.1","language":"en","source_language":"en","source_url":"https://github.com/chanzuckerberg/miniwdl","tags":["WDL","workflow-engine","bioinformatics","cli","data-science","genomics"],"install":[{"cmd":"pip install miniwdl","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"miniwdl requires Python 3.8 or newer.","package":"python","optional":false}],"imports":[{"note":"The primary `run` function for executing WDLs is found within the `runner` submodule.","wrong":"import miniwdl.run","symbol":"run","correct":"from miniwdl import runner"},{"note":"The `main` submodule provides access to CLI functionalities programmatically.","symbol":"main","correct":"from miniwdl import main"},{"note":"The `wdl` submodule contains parsing and AST (Abstract Syntax Tree) functionalities for WDL documents.","symbol":"wdl","correct":"from miniwdl import wdl"}],"quickstart":{"code":"import miniwdl.runner\nimport os\n\n# Create a simple WDL file for demonstration\nwdl_content = \"\"\"\nversion 1.0\nworkflow hello {\n  input { String name }\n  call hello_task { input: name = name }\n}\ntask hello_task {\n  input { String name }\n  command { echo \"Hello, ${name}!\" }\n  output { String message = read_string(stdout()) }\n}\n\"\"\"\nwith open(\"hello.wdl\", \"w\") as f:\n    f.write(wdl_content)\n\n# Define inputs as a dictionary\ninputs = {\"hello.name\": \"WDL User\"}\n\n# Run the WDL workflow\ntry:\n    run_result = miniwdl.runner.run(\n        wdl=\"hello.wdl\",\n        inputs=inputs,\n        dir=os.getcwd() # Specify directory where WDL is found\n    )\n    # Access outputs\n    print(f\"Workflow output: {run_result.outputs['hello.hello_task.message']}\")\nexcept Exception as e:\n    print(f\"An error occurred: {e}\")\nfinally:\n    # Clean up the dummy WDL file\n    if os.path.exists(\"hello.wdl\"):\n        os.remove(\"hello.wdl\")\n","lang":"python","description":"This quickstart demonstrates how to programmatically run a simple WDL workflow using `miniwdl.runner.run`. It creates a temporary WDL file, defines inputs, executes the workflow, and prints the output."},"warnings":[{"fix":"Explicitly cast optional values to their non-optional counterparts using `as String` or ensure the target variable is also optional. For example, `my_optional_string_var as String`.","message":"Implicit coercions from optional types (e.g., `String?`) to non-optional types (`String`) were disallowed starting in v1.9.0.","severity":"breaking","affected_versions":">=1.9.0"},{"fix":"If your tasks rely on login shell features (e.g., specific `~/.bashrc` settings), you can restore this behavior by configuring `[task_runtime] bash_cmd_shell_opts = ['-l']` in your miniwdl configuration file.","message":"The default `-l` (login shell) flag for task command bash interpreters was removed in v1.9.0. This can change the environment available to your tasks.","severity":"breaking","affected_versions":">=1.9.0"},{"fix":"Upgrade to miniwdl v1.13.1 or newer to resolve `asyncio.get_event_loop()` related errors on modern Python versions.","message":"With Python 3.10+ and `asyncio`, you might encounter errors related to the event loop. v1.13.1 fixed an issue with `asyncio.get_event_loop()`.","severity":"gotcha","affected_versions":"<1.13.1 on Python 3.10+"},{"fix":"Review WDLs for reliance on specific command indentation or implicit field handling in structs. Update WDLs to conform strictly to WDL 1.1 specification and declare all struct fields explicitly.","message":"v1.13.0 introduced changes for WDL 1.1 spec compliance, including dedenting task commands before interpolation and stricter type checking for struct literals. This could subtly alter behavior for existing WDLs.","severity":"gotcha","affected_versions":">=1.13.0"},{"fix":"Ensure your `setuptools` package is up-to-date (`pip install --upgrade setuptools`) if you encounter any import or packaging-related errors.","message":"Internal migration from `pkg_resources` to `importlib_metadata` in v1.13.1. While this primarily affects miniwdl's internals, outdated `setuptools` in the user environment could cause issues.","severity":"gotcha","affected_versions":"N/A (internal change)"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Upgrade miniwdl to version 1.13.1 or newer. This version includes a fix for this `asyncio` compatibility problem.","cause":"This error typically occurs on Python 3.10+ when asynchronous code attempts to access an event loop that hasn't been set up or has been closed. miniwdl versions prior to 1.13.1 had specific issues with `asyncio.get_event_loop()`.","error":"RuntimeError: There is no current event loop in thread '...'"},{"fix":"Explicitly handle optional values. If the value is known to be present, cast it using `as String`. If it might be null, ensure the receiving variable is also optional, or use conditional logic (`if defined(x) then x else 'default'`).","cause":"You are attempting to use an optional WDL variable (e.g., `String?`) in a context that requires a non-optional type (e.g., `String`) without explicitly handling the optionality. This behavior was disallowed from v1.9.0.","error":"WDL.Error.TypeError: Optional[String] cannot be coerced to String"},{"fix":"Provide the path to your WDL file, e.g., `miniwdl run my_workflow.wdl inputs.json`.","cause":"When running miniwdl from the command line, you must specify the path to your main WDL workflow file.","error":"miniwdl: error: the following arguments are required: WDL_FILE"},{"fix":"Ensure all fields in your struct literal exactly match the fields defined in your WDL struct type. Review the WDL 1.1 specification for struct definition and usage.","cause":"You are providing a struct literal with a field that is not defined in the corresponding WDL struct type, or there's a typo. This became stricter with WDL 1.1 compliance.","error":"WDL.Error.SyntaxError: unknown field \"xyz\" in struct type MyStruct"}]}