Install & Compatibility
Where this runs
tested against v0.25.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.95 runs
installs and imports cleanly · install 0.0s · import 0.012s · 19.9MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 1.6s · import 0.006s · 21MB
18MB installed
● package 18MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Language
✓ from tree_sitter import Language
Parser
✓ from tree_sitter import Parser
tree_sitter_python
✓ import tree_sitter_python
This quickstart demonstrates how to load the Python grammar and parse a simple Python code snippet. It initializes a `Language` object using `tree_sitter_python.language()`, creates a `Parser`, and then parses a byte string of Python code into a syntax tree. The root node's type and its first child's type are printed.
from tree_sitter import Language, Parser
import tree_sitter_python
# Initialize the Python language grammar
PY_LANGUAGE = Language(tree_sitter_python.language())
# Create a parser and configure it to use the Python language
parser = Parser(PY_LANGUAGE)
# Source code to parse
code = b"""
def greet(name):
print(f"Hello, {name}!")
greet("World")
"""
# Parse the code
tree = parser.parse(code)
# Get the root node of the syntax tree
root_node = tree.root_node
# Print the type of the root node and its first child (for demonstration)
print(f"Root node type: {root_node.type}")
if root_node.children:
print(f"First child type: {root_node.children[0].type}")
# Expected output might vary slightly but should show 'module' and 'function_definition'
Debug
Known issues
breakingThe `tree-sitter` core library and its language grammars (like `tree-sitter-python`) use an internal ABI version. Incompatibilities can arise if the `tree-sitter` Python package and the `tree-sitter-python` grammar package are not aligned in their supported ABI versions, leading to runtime errors.fixAlways ensure `tree-sitter` and `tree-sitter-python` are updated to compatible versions, ideally the latest available. For example, `tree-sitter` 0.25.0 and later primarily support ABI version 15.
affects: tree-sitter < 0.25.0, tree-sitter-python < 0.25.0
breakingThe `tree-sitter` core Python bindings (`py-tree-sitter` package) introduced significant breaking changes in version `0.24.0`, affecting method signatures for `Parser.parse`, `Query.captures`, `Query.matches`, and deprecated `Language.query`.fixReview the official `py-tree-sitter` documentation or GitHub releases for `v0.24.0` for detailed API changes. Update code to use new signatures, e.g., using `Query(language, source)` instead of `Language.query(source)`.
affects: py-tree-sitter >= 0.24.0
deprecatedVersion 0.24.0 of `tree-sitter-python` dropped compatibility with Python 3.9.fixUpgrade your Python environment to Python 3.10 or newer.
affects: tree-sitter-python >= 0.24.0
gotchaWhen working with `tree-sitter` and its Python bindings, parsing very large or complex codebases, especially with certain grammar versions (e.g., specific `tree-sitter-bash` versions), has been reported to cause high memory usage or even memory leaks.fixMonitor memory usage for large inputs. If excessive memory consumption is observed, check for updates to both `tree-sitter` and the specific language grammar (`tree-sitter-python`). Consider processing code in smaller chunks if possible.
affects: Potentially all versions, dependent on grammar and input size
gotchaWhile `tree-sitter-python` provides a pre-compiled grammar, building custom or third-party `tree-sitter` grammars for other languages requires a C compiler and Node.js for compilation, which can be a common setup hurdle for new users.fixEnsure you have a C compiler (like GCC or Clang) and Node.js installed and accessible in your PATH if you intend to compile `tree-sitter` grammars from source.
affects: All versions (for custom grammars)
Upgrade
Version history
0.25.0latest on PyPI · released Sep 11, 2025
Audit
Dependencies
tree-sitterrequiredCore Python bindings for the Tree-sitter parsing library.
pythonrequiredRequires Python 3.10 or newer. Version 0.24.0 dropped support for Python 3.9.