ast-grep-py

library0.45.2pypypi✓ verified 23d ago

ast-grep-py provides Python bindings for ast-grep, a powerful structural code search and rewrite engine. It enables developers to query and transform code using abstract syntax tree (AST) patterns, supporting multiple programming languages. The current version is 0.42.1, and the library maintains a rapid release cadence with frequent minor and patch updates, often multiple times a month.

devops data

pip install ast-grep-py

github ↗package ↗docs ↗changelog ↗

INSTALL

IMPORT

SIG · AST-GREP-PY

ast-grep-py

devopspythonv0.45.2

Install

2.0s avg

Import

15ms

Disk

58MB

Pass rate

4/ 10

Env Coverage4 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.45.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

musl

glibc

py 3.10

✕ build_error

✓ 2.1s

py 3.11

✕ build_error

✓ 2s

py 3.12

✕ build_error

✓ 1.7s

py 3.13

✕ build_error

✓ 2.1s

py 3.9

✕ build_error

58MB installed

● package 58MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

SgRoot

✓ from ast_grep_py import SgRoot

SgNode

✓ from ast_grep_py import SgNode

SgMatch

✓ from ast_grep_py import SgMatch

SgPattern

✓ from ast_grep_py import SgPattern

Initialize an `SgRoot` with Python code, find patterns like function definitions, and replace `print()` calls with `logger.info()` using ast-grep's pattern matching syntax. Note that `replace()` returns a new `SgRoot` object.

from ast_grep_py import SgRoot python_code = """ def my_function(a, b): result = a + b print(f"Result: {result}") return result """ # Create an SgRoot instance. Language defaults to Python. root = SgRoot(code=python_code) # Find all function definitions using an ast-grep pattern # '$FUN' and '$$$' are metavariables matching identifiers and multiple statements/expressions respectively. matches = root.find_all("def $FUN($$$):") print("Found functions:") for m in matches: print(f"- {m.text()}") # Replace print statements with a logger.info call # SgRoot.replace returns a new SgRoot instance with the changes. new_code_root = root.replace( pattern='print($$$)', replacement='logger.info($$$)' ) print("\nCode after replacement:") print(new_code_root.text())

ast-grep --version

Debug

Known issues

gotchaThe pattern matching syntax used by ast-grep-py (e.g., `$VAR`, `$$$`) is specific to ast-grep and differs significantly from standard regular expressions or typical AST traversal libraries. Users must learn this syntax to effectively utilize the library.

fix

Refer to the official ast-grep pattern documentation at https://ast-grep.github.io/ast-grep/guide/pattern.html

affects: All versions

gotchaWhen analyzing code written in languages other than Python, it is crucial to explicitly specify the `lang` parameter during `SgRoot` initialization (e.g., `SgRoot(code=my_js_code, lang='javascript')`). The default language is Python.

fix

Always pass the `lang` argument for non-Python code to ensure correct parsing and pattern matching.

affects: All versions

gotchaMethods like `SgRoot.replace()` do not modify the original `SgRoot` instance in-place. Instead, they return a *new* `SgRoot` object containing the modified code. Users expecting mutable behavior might inadvertently ignore the returned value.

fix

Always assign the result of `replace()` or similar modification methods to a new variable or reassign to the original variable to capture the changes.

affects: All versions

gotchaWhile ast-grep is implemented in Rust for performance, the Python bindings introduce a layer of overhead. For extremely large codebases or highly performance-critical scenarios involving frequent AST operations, users should benchmark the Python bindings against the native Rust CLI to ensure it meets their performance requirements.

fix

Benchmark critical operations on representative codebases. Consider direct use of the ast-grep CLI for maximum performance if the Python binding overhead is unacceptable.

affects: All versions

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'ast_grep'

This error occurs when the 'ast-grep-py' package is not installed in your Python environment.

fix

Install the package using pip: 'pip install ast-grep-py'.

ImportError: cannot import name 'SgNode' from 'ast_grep'

This error occurs when attempting to import 'SgNode' from 'ast_grep', but the module does not contain this name.

fix

Ensure that 'SgNode' is correctly defined in the 'ast_grep' module or check for typos in the import statement.

TypeError: find() missing 1 required positional argument: 'pattern'

This error occurs when calling the 'find' method without providing the required 'pattern' argument.

fix

Provide the 'pattern' argument when calling 'find', e.g., 'node.find(pattern="print($A)")'.

AttributeError: module 'ast_grep' has no attribute 'find'

This error occurs when attempting to call the 'find' method on the 'ast_grep' module, but the module does not have this attribute.

fix

Ensure that you are calling 'find' on an instance of 'SgNode' or 'SgRoot', not directly on the 'ast_grep' module.

ValueError: Unsupported language: 'java'

This error occurs when specifying a language that is not supported by 'ast-grep-py'.

fix

Use a supported language, such as 'python' or 'javascript', when initializing 'SgRoot'.

Upgrade

Version history

0.45.2latest on PyPI · released Aug 23, 2026

Audit

Dependencies

No dependency data recorded yet.

Agent activity

31 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/ast-grep/ast-grep ↗

packagehttps://pypi.org/project/ast-grep-py/ ↗

docshttps://ast-grep.github.io/ ↗

changeloghttps://github.com/ast-grep/ast-grep/blob/main/CHANGELOG.md ↗