Install & Compatibility
Where this runs
tested against v0.7.2 · 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.95 runs
installs and imports cleanly · install 0.0s · import 0.054s · 18.1MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 1.5s · import 0.054s · 19MB
16MB installed
● package 16MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
language
✓ from tree_sitter_yaml import language
✗ from tree_sitter import Language, Parser
HIGHLIGHTS_QUERY
✓ from tree_sitter_yaml import HIGHLIGHTS_QUERY
This quickstart demonstrates how to initialize the Tree-sitter parser with the `tree-sitter-yaml` grammar, parse a YAML byte string, traverse the resulting syntax tree, and execute a basic Tree-sitter query to extract key-value pairs.
import tree_sitter_yaml
from tree_sitter import Language, Parser
# Load the YAML language grammar
YAML_LANGUAGE = Language(tree_sitter_yaml.language())
# Initialize the parser with the YAML language
parser = Parser()
parser.set_language(YAML_LANGUAGE)
# Example YAML content
yaml_code = b"""
name: John Doe
age: 30
cities:
- New York
- London
"""
# Parse the YAML code
tree = parser.parse(yaml_code)
# Get the root node of the syntax tree
root_node = tree.root_node
# Print the tree structure (simplified for quickstart)
def print_node(node, indent=0):
print(' ' * indent + f"Type: {node.type}, Text: {node.text.decode('utf8')}")
for child in node.children:
print_node(child, indent + 1)
print_node(root_node)
# Example: Find a specific node type (e.g., 'pair')
query = YAML_LANGUAGE.query("""
(pair (key) @key (value) @value)
""")
captures = query.captures(root_node)
print("\nKey-Value Pairs:")
for node, name in captures:
if name == 'key':
key_text = node.text.decode('utf8')
elif name == 'value':
value_text = node.text.decode('utf8')
print(f" Key: {key_text}, Value: {value_text}")
Debug
Known issues
breakingTree-sitter grammars are compiled against a specific ABI version of the core Tree-sitter library. Updating the `tree-sitter` Python package (or underlying C library) without a corresponding `tree-sitter-yaml` update can lead to 'Incompatible language version' errors.fixEnsure `tree-sitter-yaml` and the core `tree-sitter` library are compatible. If you encounter this error, try updating both packages to their latest versions or consult release notes for compatibility information.
affects: All versions of `tree-sitter-yaml` when `tree-sitter` core ABI changes.
gotchaDirectly using the `tree-sitter` library often involves compiling grammars. However, `tree-sitter-yaml` (and `tree-sitter-languages`) provides pre-compiled binary wheels. Attempting manual compilation (`Language.build_library()`) for these packages is usually unnecessary and can lead to errors or confusion if the package already supplies a pre-built grammar.fixFor `tree-sitter-yaml`, simply load the `language()` function directly. If using `tree-sitter-languages`, use `get_language()` and `get_parser()`. Only manually compile if you are working with a grammar that does not provide pre-built Python wheels.
affects: All versions.
gotchaSome users have reported memory leaks or unexpected highlighting issues when reusing Tree-sitter YAML parsers, especially with very large files or specific text editing patterns in integrated environments (e.g., Neovim). This can manifest as broken highlighting or increased memory consumption.fixIf experiencing memory issues with reused parsers or large YAML files, consider re-initializing the parser for new files, ensuring the correct language name is passed, or investigating if the issue lies within the integrating application (e.g., editor plugin). Consult the `tree-sitter` core library issues for potential upstream fixes or workarounds.
affects: Potentially all versions, depending on usage context and core `tree-sitter` interactions.
breakingDownstream tools relying on Tree-sitter grammars (e.g., `nvim-treesitter` for syntax highlighting) may experience breaking changes if Tree-sitter's internal capture group naming conventions are updated. This requires corresponding updates in client applications' configurations, queries, or color schemes.fixUpdate the consuming application or its configuration (e.g., Neovim plugins, color schemes, custom queries) to align with the new Tree-sitter capture group names. Refer to the specific application's documentation or migration guides for details on affected groups (e.g., `@parameter` to `@variable.parameter`).
affects: Relevant for integrations like `nvim-treesitter` from ~v0.9.x to v0.10.x and newer, specifically for highlighting groups.
Upgrade
Version history
0.7.2latest on PyPI · released Oct 7, 2025
Audit
Dependencies
tree-sitterrequiredThis is the core Python binding library for Tree-sitter, required to load and use the grammar for parsing.
tree-sitter-languagesoptionalProvides pre-compiled binary wheels for many Tree-sitter grammars, simplifying loading and avoiding manual compilation steps, though tree-sitter-yaml can be loaded directly.