Install & Compatibility
Where this runs
tested against v0.27.0 · 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.000s · 63.3MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 6.7s · import 0.000s · 64MB
63MB installed
● package 63MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
converter
✓ from gxformat2 import converter
✗ from gxformat2.yaml import parse_yaml_workflow
export
✓ from gxformat2 import export
from_galaxy_native
✓ from gxformat2 import from_galaxy_native
This quickstart demonstrates how to parse a Format 2 workflow from a YAML string into a Python object using `parse_yaml_workflow`, and then convert it to the native Galaxy `.ga` format using `dump_format2_workflow_to_native`. It also shows how to access basic properties of the parsed workflow model.
from gxformat2.yaml import parse_yaml_workflow
from gxformat2.converter import dump_format2_workflow_to_native
import yaml
# Example Format 2 Workflow content (minimal example)
workflow_content = '''
class: GalaxyWorkflow
inputs:
- id: input_file
type: File
steps:
- id: cat_tool
tool_id: cat1
in:
input1: input_file
outputs:
- id: output_file
outputSource: cat_tool/out_file
'''
# 1. Parse a Format 2 YAML workflow string
# In a real scenario, you'd load this from a .gxwf.yml file
workflow_path = '/tmp/my_workflow.gxwf.yml'
with open(workflow_path, 'w') as f:
f.write(workflow_content)
try:
workflow_model = parse_yaml_workflow(workflow_path)
print(f"Successfully parsed workflow: {workflow_model.label or workflow_model.id}")
# 2. Convert the Format 2 workflow model to native Galaxy .ga format
native_workflow_dict = dump_format2_workflow_to_native(workflow_model)
print("\nConverted to native Galaxy workflow (excerpt):")
print(yaml.dump(native_workflow_dict, indent=2, default_flow_style=False)[:200] + '...') # Print first 200 chars
# You can access properties of the parsed model
print(f"\nNumber of steps: {len(workflow_model.steps)}")
print(f"First step tool_id: {workflow_model.steps[0].tool_id}")
except Exception as e:
print(f"An error occurred: {e}")
Debug
Known issues
gotchaThe Format 2 workflow description is still considered somewhat experimental. It may undergo small, potentially backward-incompatible changes, particularly until it is exported by Galaxy as the default format. Users should regularly review changelogs for updates.fixStay updated with releases, consult the official documentation, and test workflows after upgrading the library or Galaxy.
affects: All versions up to 0.24.0
breakingSupport for Python 3.5 was dropped, and Python 3.9 was added as the minimum required version in `gxformat2` v0.16.0.fixEnsure your environment uses Python 3.9 or newer. Upgrade your Python interpreter if necessary.
affects: < 0.16.0 to >= 0.16.0
gotchaWhen defining workflows, use the `label` field instead of `name` for workflow validation against the schema. While Galaxy may still process `name` for legacy reasons, `label` is the correct attribute for adherence to the Format 2 schema.fixAlways use `label: Your Workflow Name` for workflow definitions in Format 2 YAML files to ensure proper validation.
affects: All versions
deprecatedThe `ImportOptions` class is being replaced by `ConversionOptions` for conversion and expansion layers, as part of an architectural refactor. Using `ImportOptions` might become deprecated or removed in future versions.fixMonitor future `gxformat2` releases for the official switch. When `ConversionOptions` is introduced, migrate any usage of `ImportOptions` to the new class.
affects: Future versions beyond 0.24.0 (as per recent GitHub discussions)
Upgrade
Version history
0.27.0latest on PyPI · released May 27, 2026
Audit
Dependencies
No dependency data recorded yet.