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.050s · 17.9MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 1.5s · import 0.050s · 18MB
16MB installed
● package 16MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
language
✓ from tree_sitter_regex import language
✗ from tree_sitter import Language; language = Language.build_library('build/my-regex-language.so', ['path/to/tree-sitter-regex'])
The `tree-sitter-regex` package provides a pre-compiled `Language` object via its `language()` function, simplifying setup. Manual compilation or incorrect dynamic loading is not needed.
This quickstart demonstrates how to initialize the Tree-sitter parser with the `tree-sitter-regex` grammar, parse a regular expression string, and inspect the resulting syntax tree. It shows how to get the `Language` object, set it for the parser, and retrieve node information.
import tree_sitter
from tree_sitter_regex import language
# Get the pre-compiled Tree-sitter Language object for regex
REGEX_LANGUAGE = language()
# Create a parser instance
parser = tree_sitter.Parser()
parser.set_language(REGEX_LANGUAGE)
# Define a regex string to parse (must be bytes)
regex_string = r"^([a-zA-Z0-9_\-]+)\s*=\s*(.+)$"
encoded_regex = bytes(regex_string, "utf8")
# Parse the regex string
tree = parser.parse(encoded_regex)
# Print the S-expression representation of the syntax tree
print("--- S-expression Tree ---")
print(tree.root_node.sexp())
# Traverse and print some nodes
print("\n--- Node Details ---")
root = tree.root_node
for child in root.children:
print(f"Type: {child.type}, Text: {child.text.decode('utf8')}, Start: {child.start_point}, End: {child.end_point}")
# Example: Find all `_token_name` nodes
print("\n--- Token Names Found ---")
for node in root.descendant_for_point_range((0,0), (len(encoded_regex), 0)).children:
if node.type == '_token_name':
print(f"Found token name: {node.text.decode('utf8')}")
Debug
Known issues
gotchaThe `tree-sitter-regex` package provides a `language()` function that directly returns the pre-compiled `tree_sitter.Language` object. Do not attempt to manually compile the grammar or dynamically load 'regex' using `tree_sitter.Language.build_library` or `Language.load()`, as this can lead to compilation errors or `LanguageNotFound` exceptions.fixAlways import and call `from tree_sitter_regex import language` to get the grammar object: `regex_language = language()`.
affects: All versions
gotchaThe `tree_sitter.Parser.parse()` method strictly expects a `bytes` object as input, not a Python `str`. Passing a string directly will result in a `TypeError`.fixEnsure your input string is explicitly encoded to bytes, typically UTF-8, before passing it to `parse()`: `parser.parse(your_string.encode('utf8'))` or `parser.parse(bytes(your_string, 'utf8'))`. affects: All `tree-sitter` and `tree-sitter-regex` versions
gotchaWhen accessing node text (e.g., `node.text`), the returned value is always a `bytes` object. For human-readable output or string manipulation, this `bytes` object must be decoded.fixAfter retrieving `node.text`, decode it using the appropriate encoding, usually UTF-8: `node.text.decode('utf8')`. affects: All `tree-sitter` and `tree-sitter-regex` versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'tree_sitter_regex'
The `tree-sitter-regex` Python package has not been installed in your current environment.
fixpip install tree-sitter-regex
ImportError: cannot import name 'Language' from 'tree_sitter_regex'
The `Language` class for creating Tree-sitter parsers belongs to the core `tree-sitter` library, not the grammar binding itself.
fixfrom tree_sitter import Language
TypeError: Parser.set_language() argument must be tree_sitter._language.Language, not function
The `language` function imported from `tree_sitter_regex` must be called to return the actual `Language` object before being passed to `set_language`.
fixparser.set_language(language())
Upgrade
Version history
0.25.0latest on PyPI · released Sep 13, 2025
Audit
Dependencies
tree-sitterrequiredRequired to use the grammar for parsing, as tree-sitter-regex only provides the grammar bindings, not the core parser library.