{"id":1874,"library":"pyyaml-ft","title":"PyYAML-ft (Free-Threading)","description":"PyYAML-ft is a fork of the popular PyYAML library, providing a full-featured YAML parser and emitter for Python. Its primary purpose is to add support for free-threading builds of CPython, specifically targeting Python 3.13 and newer, where the Global Interpreter Lock (GIL) is absent. This addresses thread-safety issues that are more easily triggered in free-threaded environments and ensures ABI compatibility. The library is currently at version 8.0.0 and maintains an active release cadence in sync with free-threading Python developments.","status":"active","version":"8.0.0","language":"en","source_language":"en","source_url":"https://github.com/Quansight-Labs/pyyaml-ft/","tags":["yaml","serialization","free-threading","python3.13","parsing"],"install":[{"cmd":"pip install pyyaml-ft","lang":"bash","label":"Install pyyaml-ft"}],"dependencies":[{"reason":"Requires Python 3.13 or newer, particularly for free-threading builds.","package":"python","optional":false}],"imports":[{"note":"As of v8.0.0, the module was renamed from 'yaml' to 'yaml_ft' to allow coexistence with upstream PyYAML.","wrong":"import yaml","symbol":"yaml_ft","correct":"import yaml_ft"},{"note":"It is generally safer to use `safe_load` and `safe_dump` to prevent arbitrary code execution from untrusted YAML sources.","symbol":"safe_load, safe_dump","correct":"from yaml_ft import safe_load, safe_dump"}],"quickstart":{"code":"import io\n\ntry:\n    import yaml_ft as yaml\nexcept ModuleNotFoundError:\n    # Fallback or for environments where pyyaml-ft isn't the primary YAML lib\n    import yaml \n\n# Sample YAML data\nyaml_data = \"\"\"\nname: Alice\nage: 30\noccupations:\n  - Software Engineer\n  - Technical Writer\nis_active: true\n\"\"\"\n\n# Load YAML data\ndata = yaml.safe_load(yaml_data)\nprint(\"Loaded Data:\", data)\n\n# Modify data\ndata['age'] = 31\ndata['occupations'].append('Open Source Contributor')\n\n# Dump data to YAML string\noutput_stream = io.StringIO()\nyaml.safe_dump(data, output_stream, default_flow_style=False)\nprint(\"\\nDumped YAML:\")\nprint(output_stream.getvalue())\n\nprint(f\"\\nSuccessfully used {yaml.__name__} for YAML operations.\")","lang":"python","description":"This quickstart demonstrates how to load and dump YAML data using `pyyaml-ft`. It includes a conditional import for compatibility and uses `safe_load`/`safe_dump` for secure processing of YAML data."},"warnings":[{"fix":"Update imports to `import yaml_ft` or use `try: import yaml_ft as yaml except ModuleNotFoundError: import yaml` for compatibility with projects supporting both PyYAML and PyYAML-ft.","message":"The primary module name has changed from `yaml` to `yaml_ft` starting with v8.0.0. Direct `import yaml` will fail if only `pyyaml-ft` is installed.","severity":"breaking","affected_versions":">=8.0.0"},{"fix":"Ensure that any custom YAML types or resolvers are registered within each thread's initialization function or before processing YAML in that thread.","message":"Custom constructors, representers, and resolvers (`add_constructor`, `add_representer`, `add_implicit_resolver`, `add_path_resolver`) now use thread-local registries. These must be explicitly re-registered in each new thread if used in multithreaded applications.","severity":"breaking","affected_versions":">=7.0.0"},{"fix":"Ensure your project's `requires_python` is set to `>=3.13` and consider conditional installation based on `python_version` if supporting a wider range of Python versions.","message":"PyYAML-ft is primarily designed for Python 3.13 and newer, especially free-threaded builds. While it might install on older Python versions, its free-threading benefits are specific to Python 3.13+ environments.","severity":"gotcha","affected_versions":"<8.0.0"},{"fix":"Always use `yaml_ft.safe_load()` when loading YAML from untrusted or external sources to restrict object construction to safe types.","message":"Using `yaml.load()` (or `yaml_ft.load()`) with untrusted input can lead to arbitrary code execution, as it can deserialize arbitrary Python objects. This is a well-known security vulnerability in PyYAML and applies to PyYAML-ft.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}