Install & Compatibility
Where this runs
tested against v0.24.8 · 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.050s · 17.8MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 1.5s · import 0.044s · 18MB
16MB installed
● package 16MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Language
✓ from tree_sitter_json import language
✗ from tree_sitter import Language
Parser
✓ from tree_sitter import Parser
✗ from tree_sitter import Parser
This quickstart demonstrates how to load the `tree-sitter-json` grammar, initialize a parser, and parse a basic JSON string. It also shows a simple traversal of the resulting syntax tree to access the root node's type and its direct children for a JSON object. Input code must be `bytes`.
import tree_sitter_json
from tree_sitter import Language, Parser
# Load the JSON language grammar
JSON_LANGUAGE = Language(tree_sitter_json.language())
# Create a parser and set its language
parser = Parser()
parser.set_language(JSON_LANGUAGE)
# Example JSON source code (must be bytes)
json_code = b'''
{
"name": "Alice",
"age": 30,
"isStudent": false,
"courses": ["Math", "Science"]
}
'''
# Parse the code
tree = parser.parse(json_code)
# Get the root node and print its type and text
root_node = tree.root_node
print(f"Root node type: {root_node.type}")
print(f"Root node text: {root_node.text.decode('utf8')}")
# Example: Iterate through top-level object pairs (requires understanding of JSON grammar nodes)
if root_node.type == 'object':
for child in root_node.children:
if child.type == 'pair':
key_node = child.child_by_field_name('key')
value_node = child.child_by_field_name('value')
if key_node and value_node:
print(f" Key: {key_node.text.decode('utf8')}, Value: {value_node.text.decode('utf8')}")
tree-sitter --version
Debug
Known issues
breakingThe `tree-sitter` core library (which `tree-sitter-json` relies on) had an internal ABI bump to version 15 in v0.25.0 (February 2025). Ensure your installed `tree-sitter` Python package is compatible with the ABI version used to compile `tree-sitter-json`. Mismatched versions can lead to crashes or unexpected behavior.fixAlways ensure that the `tree-sitter` Python package is kept up-to-date with `tree-sitter-json`. If issues arise, try reinstalling both packages: `pip install --upgrade tree-sitter tree-sitter-json`.
affects: tree-sitter core >=0.25.0
gotchaThe `parser.parse()` method expects input as `bytes`, not a standard Python `str`. Providing a string will result in a `TypeError`.fixEncode your input string to bytes, typically using `my_string.encode('utf8')`, before passing it to `parser.parse()`. affects: All versions
gotchaThe `tree-sitter-json` package only provides the grammar. The actual parsing engine and Python bindings are provided by the `tree-sitter` package. Forgetting to install `tree-sitter` will prevent `tree-sitter-json` from being used.fixEnsure both `tree-sitter` and `tree-sitter-json` are installed: `pip install tree-sitter tree-sitter-json`.
affects: All versions
Upgrade
Version history
0.24.8latest on PyPI · released Nov 11, 2024
Audit
Dependencies
tree-sitterrequiredProvides the core Python bindings and parsing engine required to use the tree-sitter-json grammar.