Install & Compatibility
Where this runs
tested against v0.23.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.012s · 22.3MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 1.8s · import 0.010s · 23MB
20MB installed
● package 20MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
language
✓ from tree_sitter import Language, Parser
import tree_sitter_typescript
TS_LANGUAGE = Language(tree_sitter_typescript.language(), 'typescript')
Used to load the standard TypeScript grammar.
tsx_language
✓ from tree_sitter import Language, Parser
import tree_sitter_typescript
TSX_LANGUAGE = Language(tree_sitter_typescript.tsx_language(), 'tsx')
Used to load the TSX (TypeScript React) grammar.
This quickstart demonstrates how to install `tree-sitter-typescript` and `tree-sitter`, then load both the TypeScript and TSX grammars to parse respective code snippets. It shows how to initialize a parser, set the language, parse code, and access the resulting syntax tree's root node.
from tree_sitter import Language, Parser
import tree_sitter_typescript
# Load the TypeScript grammar
TS_LANGUAGE = Language(tree_sitter_typescript.language(), 'typescript')
# Create a parser and set its language
parser = Parser()
parser.set_language(TS_LANGUAGE)
# Code to parse
ts_code = b"""interface MyInterface { name: string; age?: number; }\nconst x: MyInterface = { name: 'Alice' };"""
# Parse the code
tree = parser.parse(ts_code)
# Access the root node
root_node = tree.root_node
print(f"Parsed TypeScript root node type: {root_node.type}")
# Load the TSX grammar
TSX_LANGUAGE = Language(tree_sitter_typescript.tsx_language(), 'tsx')
parser.set_language(TSX_LANGUAGE)
# TSX code to parse
tsx_code = b"""function App() { return <div>Hello, {name}</div>; }"""
# Parse the TSX code
tree_tsx = parser.parse(tsx_code)
root_node_tsx = tree_tsx.root_node
print(f"Parsed TSX root node type: {root_node_tsx.type}")
# Example of finding a node
interface_node = root_node.children[0] # Assuming interface declaration is the first child
print(f"First node in TS: {interface_node.type}, text: {interface_node.text.decode('utf8')}")
tree-sitter --version
Debug
Known issues
breakingThe `Language.build_library` method, previously used to compile grammars in older versions of `py-tree-sitter` (prior to approximately 0.22.x), has been removed. Grammars like `tree-sitter-typescript` are now expected to be installed as pre-compiled Python packages.fixEnsure you are using a recent version of `tree-sitter` (the core Python binding) and directly `pip install tree-sitter-typescript`. Do not attempt to use `Language.build_library`.
affects: <=0.21.x of `py-tree-sitter`
breakingThe underlying `tree-sitter` core library occasionally introduces Application Binary Interface (ABI) changes (e.g., ABI 15 in v0.25.0). These changes can cause compatibility issues with older `tree-sitter` Python bindings or grammar packages if they are not updated to match the new ABI.fixAlways ensure your `tree-sitter` Python package and `tree-sitter-typescript` are kept up-to-date and compatible. If parsing issues arise after upgrading `tree-sitter`, update `tree-sitter-typescript` as well.
affects: All versions of `tree-sitter-typescript` when paired with incompatible `tree-sitter` core versions
gotchaWhile `tree-sitter-typescript` provides both TypeScript and TSX grammars, complex or less common syntax constructs (e.g., specific styled components patterns, LaTeX strings within templates, or certain advanced `import`/`export` declarations) may result in `ERROR` or `MISSING` nodes in the parsed syntax tree. This indicates the grammar could not fully parse that section.fixMonitor GitHub issues for known parsing limitations. If encountering `ERROR` nodes for valid syntax, consider reporting it as a bug to the `tree-sitter-typescript` GitHub repository.
affects: All versions
gotchaThe `tree-sitter-typescript` grammar internally relies on the `tree-sitter-javascript` grammar for JavaScript-specific constructs. However, installing `tree-sitter-typescript` via pip does not automatically install `tree-sitter-javascript` as a separate Python package. This might lead to unexpected parsing behavior or errors if the JavaScript grammar is implicitly expected for certain parts of the code.fixIf working with mixed JavaScript/TypeScript files or encountering issues that seem related to underlying JavaScript parsing, explicitly `pip install tree-sitter-javascript` alongside `tree-sitter-typescript`.
affects: All versions
Upgrade
Version history
0.23.2latest on PyPI · released Nov 11, 2024
Audit
Dependencies
tree-sitterrequiredProvides the core parsing engine and Python bindings required to load and use the grammars.