{"id":742,"library":"tree-sitter","title":"Tree-sitter Python Bindings","description":"Tree-sitter provides Python bindings to the core Tree-sitter parsing library, enabling fast, incremental parsing and the generation of concrete syntax trees for various programming languages. It's actively maintained, with frequent updates (minor and patch releases typically every few weeks or months) to keep pace with the underlying C library. The current version is `0.25.2`.","status":"active","version":"0.25.2","language":"python","source_language":"en","source_url":"https://github.com/tree-sitter/py-tree-sitter","tags":["parsing","syntax tree","AST","code analysis","compiler"],"install":[{"cmd":"pip install tree-sitter","lang":"bash","label":"Install core library"},{"cmd":"pip install tree-sitter-python","lang":"bash","label":"Install Python grammar (example)"}],"dependencies":[{"reason":"Requires Python 3.10 or newer.","package":"python","optional":false},{"reason":"Specific language grammars are often provided as separate packages (e.g., `tree-sitter-python`) for pre-compiled binaries.","package":"tree-sitter-<language>","optional":true}],"imports":[{"symbol":"Language","correct":"from tree_sitter import Language"},{"symbol":"Parser","correct":"from tree_sitter import Parser"},{"symbol":"Query","correct":"from tree_sitter import Query"},{"symbol":"QueryCursor","correct":"from tree_sitter import QueryCursor"},{"note":"It's best practice to import the language module with an alias and then access its `language()` function to avoid name collisions and for clarity. Direct import of `language` is also common but less explicit.","wrong":"from tree_sitter_python import language; PY_LANGUAGE = Language(language())","symbol":"language","correct":"import tree_sitter_python as tspython; PY_LANGUAGE = Language(tspython.language())"}],"quickstart":{"code":"import os\nfrom tree_sitter import Language, Parser\n\n# NOTE: For this to work, you need 'tree-sitter-python' installed\n# pip install tree-sitter-python\nimport tree_sitter_python as tspython\n\n# Load the Python language grammar\nPY_LANGUAGE = Language(tspython.language())\n\n# Create a parser and set its language\nparser = Parser()\nparser.set_language(PY_LANGUAGE)\n\n# Source code to parse\ncode = b\"\"\" \ndef greet(name): # type: (str) -> None\n    print(f\"Hello, {name}!\")\n\ngreet(\"World\")\n\"\"\"\n\n# Parse the code\ntree = parser.parse(code)\n\n# Get the root node and print its type\nroot_node = tree.root_node\nprint(f\"Root node type: {root_node.type}\")\n\n# Traverse the tree (example: find function definitions)\nquery_string = \"\"\" \n(function_definition\n  name: (identifier) @function.name)\n\"\"\"\nquery = PY_LANGUAGE.query(query_string)\n\ncaptures = query.captures(root_node)\nfor node, name in captures:\n    print(f\"Found function: {node.text.decode('utf8')} (capture: {name})\")","lang":"python","description":"This quickstart demonstrates how to load a language grammar (Python in this case), create a parser, parse a code string into a syntax tree, and then use Tree-sitter's query system to find specific patterns within the tree, such as function names. It highlights the typical workflow of initializing a `Language` object from a pre-compiled grammar and then using a `Parser` to process source code. Ensure the relevant language package (e.g., `tree-sitter-python`) is installed alongside `tree-sitter`."},"warnings":[{"fix":"For custom language loading, ensure you're passing a proper `PyCapsule` or using a language binding that provides it. Remove `keep_text` from `parser.parse()` calls. For queries, pre-set the desired range using `query.set_byte_range()` or `query.set_point_range()` before calling `captures()` or `matches()`.","message":"The `Language` constructor no longer accepts a raw pointer (`int`) directly but expects a capsule object. If you were dynamically loading a `.so` file, you might need to use `ctypes.CDLL` and extract the language function or adjust your loading mechanism. Additionally, `Parser.parse()` no longer accepts a `keep_text` argument, and range arguments for `Query.captures()` and `Query.matches()` have been removed; use `query.set_byte_range()` or `query.set_point_range()` instead.","severity":"breaking","affected_versions":">=0.25.0"},{"fix":"Upgrade your Python environment to 3.10 or later. Migrate away from `Language(ptr: int)` by using official language binding packages (e.g., `tree-sitter-python`) which provide a `language()` function. Update code using `Node.child_containing_descendant` to equivalent newer methods or tree traversal logic.","message":"Python 3.9 is no longer supported; the library now requires Python 3.10 or newer. The `Language(ptr: int)` constructor was deprecated, urging users to use language binding packages instead of raw pointers. The method `Node.child_containing_descendant` was also deprecated.","severity":"breaking","affected_versions":">=0.24.0"},{"fix":"Ensure that the `tree-sitter` package and any `tree-sitter-<language>` packages you use are compatible by checking their release notes or by installing versions known to work together. If encountering issues, try aligning their versions, typically by upgrading/downgrading one or both packages.","message":"Incompatibilities can arise between the `tree-sitter` Python package and specific `tree-sitter-<language>` grammar packages if their underlying Tree-sitter ABI versions differ. This can lead to runtime errors when loading languages.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Monitor memory usage closely in production. For large inputs, consider processing files in chunks or optimizing your queries to reduce the scope. Report any persistent, unexplainable memory growth as a bug to the project maintainers, providing a minimal reproducible example.","message":"High memory usage has been reported in certain scenarios, particularly when parsing very large files or using complex grammars, potentially indicating memory leaks in specific contexts or substantial resource requirements of the core library.","severity":"gotcha","affected_versions":"All versions"},{"fix":"For unsupported languages, follow the official Tree-sitter documentation for compiling custom grammars. Then, use `from tree_sitter import Language; MY_LANGUAGE = Language(f'path/to/my_language.so', 'my_language_name')` to load it, ensuring the ABI version matches. Avoid `tree-sitter-languages` in new projects.","message":"While many languages have `tree-sitter-<language>` packages, for less common languages or custom grammars, you might need to manually compile the grammar into a shared library (`.so` or `.dll`) and then load it. The `tree-sitter-languages` package, which simplifies loading, is currently unmaintained and may have compatibility issues with newer `tree-sitter` versions.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Verify the integrity of your `tree-sitter` installation by reinstalling it (`pip install --force-reinstall tree-sitter`). Ensure there are no conflicting packages or unusual environment configurations that might interfere with the package's functionality. If the issue persists, consider trying a different minor version of `tree-sitter` or consulting the project's issue tracker for known environment-specific problems.","message":"The `tree_sitter.Parser` object reports an `AttributeError` indicating it lacks the `set_language` method. This method is expected to be present in `tree-sitter` version 0.23.2, suggesting a potential issue with the package installation, corruption, or an unexpected environment interaction preventing the method from being exposed.","severity":"breaking","affected_versions":"0.23.2"},{"fix":"Initialize the `Parser` with the `language` argument (e.g., `parser = Parser(language=MY_LANGUAGE)`) or assign the language directly to the `language` property (e.g., `parser.language = MY_LANGUAGE`).","message":"The `Parser.set_language()` method has been removed.","severity":"breaking","affected_versions":">=0.20.0"}],"env_vars":null,"last_verified":"2026-05-12T18:28:59.571Z","next_check":"2026-06-26T00:00:00.000Z","problems":[{"fix":"pip install tree-sitter","cause":"The `tree-sitter` Python package is not installed in your current environment or is not accessible.","error":"ModuleNotFoundError: No module named 'tree_sitter'"},{"fix":"Install the \"Build Tools for Visual Studio 2022\" (or 2019) from Microsoft's website, ensuring to select the 'Desktop development with C++' workload during installation.","cause":"Building Tree-sitter language grammars or compiling the `py-tree-sitter` package requires a C/C++ compiler, which is missing on Windows.","error":"error: Microsoft Visual C++ 14.0 or greater is required."},{"fix":"Ensure `tree_sitter.Language.build_library()` successfully compiles the grammar, verify the `output_path` matches where you later try to load it, and confirm the `source_paths` are correct.","cause":"The compiled shared library for the Tree-sitter language grammar could not be found, likely because `tree_sitter.Language.build_library()` failed or the specified path is incorrect.","error":"FileNotFoundError: [Errno 2] No such file or directory: 'build/my-language.so'"},{"fix":"parser.language = language","cause":"You are attempting to use an outdated method (`set_language`) on the `tree_sitter.Parser` object; the API has changed.","error":"AttributeError: 'Parser' object has no attribute 'set_language'"}],"ecosystem":"pypi","meta_description":null,"install_score":100,"install_tag":"verified","quickstart_score":0,"quickstart_tag":"stale","pypi_latest":"0.25.2","install_checks":{"last_tested":"2026-05-12","tag":"verified","tag_description":"installs cleanly on critical runtimes, fast import, recently tested","results":[{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":0.01,"mem_mb":0.5,"disk_size":"19.2M"},{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":"66.2M"},{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.01,"mem_mb":0.5,"disk_size":"19.2M"},{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":1.6,"import_time_s":0,"mem_mb":0.5,"disk_size":"20M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":1.5,"import_time_s":null,"mem_mb":null,"disk_size":"137M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0,"mem_mb":0.5,"disk_size":"20M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":0.02,"mem_mb":0.7,"disk_size":"21.0M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":"72.5M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.02,"mem_mb":0.7,"disk_size":"21.0M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":1.6,"import_time_s":0.02,"mem_mb":0.7,"disk_size":"22M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":1.6,"import_time_s":null,"mem_mb":null,"disk_size":"144M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.01,"mem_mb":0.7,"disk_size":"22M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":0.01,"mem_mb":0.6,"disk_size":"12.9M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":"63.0M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.01,"mem_mb":0.6,"disk_size":"12.9M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":1.5,"import_time_s":0.01,"mem_mb":0.6,"disk_size":"14M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":1.4,"import_time_s":null,"mem_mb":null,"disk_size":"134M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.01,"mem_mb":0.6,"disk_size":"14M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":0.01,"mem_mb":0.7,"disk_size":"12.6M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":"59.6M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.02,"mem_mb":0.7,"disk_size":"12.5M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":1.5,"import_time_s":0.01,"mem_mb":0.5,"disk_size":"14M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":1.4,"import_time_s":null,"mem_mb":null,"disk_size":"133M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.01,"mem_mb":0.5,"disk_size":"13M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":0.01,"mem_mb":0.5,"disk_size":"18.5M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":"65.4M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.01,"mem_mb":0.5,"disk_size":"18.5M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":1.8,"import_time_s":0,"mem_mb":0.5,"disk_size":"19M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":1.7,"import_time_s":null,"mem_mb":null,"disk_size":"137M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.01,"mem_mb":0.5,"disk_size":"19M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null}]},"quickstart_checks":{"last_tested":"2026-04-24","tag":"stale","tag_description":"widespread failures or data too old to trust","results":[{"runtime":"python:3.10-alpine","exit_code":1},{"runtime":"python:3.10-slim","exit_code":1},{"runtime":"python:3.11-alpine","exit_code":1},{"runtime":"python:3.11-slim","exit_code":1},{"runtime":"python:3.12-alpine","exit_code":1},{"runtime":"python:3.12-slim","exit_code":1},{"runtime":"python:3.13-alpine","exit_code":1},{"runtime":"python:3.13-slim","exit_code":1},{"runtime":"python:3.9-alpine","exit_code":1},{"runtime":"python:3.9-slim","exit_code":1}]}}