---
id: ast-grep-py
version: "0.45.1"
license: MIT
license_treatment: permissive
maintenance: active
---

# ast-grep-py — Structural Search and Rewrite code at large scale using precise AST pattern.

License: permissive · Maintenance: active · Downloads: 1.2M/mo

## What it is and what it does

ast-grep-py exposes ast-grep's code search and rewriting engine to Python programs. It lets you define patterns that match code structure—not just text—and then find, analyze, or transform matching code at scale. The package is a native Rust binding compiled to wheels, so it has no Python runtime dependencies and runs efficiently on modern Python versions.

You would use this when you need to perform structural code analysis or refactoring that text regex cannot handle: finding all calls to a deprecated function across a codebase, rewriting patterns to use a new API, or enforcing code style rules based on syntax tree shape. The API is programmatic, so you integrate it into scripts, linters, or CI pipelines rather than using a command-line tool.

Use it for:

- Search for and refactor all uses of a deprecated API across a large codebase in one pass.
- Enforce custom code style rules by matching specific AST patterns and flagging violations.
- Automate codemod tasks—e.g., migrate from one library to another—by pattern-matching and rewriting code structure.
- Build custom linters that detect anti-patterns or security issues based on syntax tree shape.
- Analyze code structure programmatically to gather metrics or generate reports on code patterns.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

ast-grep-py is a Python binding for ast-grep, a tool that searches, lints, and rewrites code using precise abstract syntax tree patterns.

Yes, if you need structural code search or rewriting beyond regex. The package is actively maintained, has no security vulnerabilities, uses a permissive MIT license, and is well-distributed across platforms. Medium install friction is acceptable for a compiled tool. Start with the official API guide to confirm the pattern syntax and API surface fit your use case.

## Install

pip install ast-grep-py
uv add ast-grep-py
poetry add ast-grep-py

## Installing ast-grep-py

Before you install: Medium install friction due to compiled wheels, but well-supported across multiple Python versions on Linux, macOS, and Windows. Active maintenance with a release 7 days old and 15516 repository stars.

License in practice: MIT license is permissive; you may use, modify, and distribute this package freely in commercial or private projects with minimal restrictions.

Quickstart:

pip install ast-grep-py

# See https://ast-grep.github.io/guide/api-usage.html for pattern and search examples

Requires Python 3.8 or later; prebuilt wheels are available for common platforms, but installation may require a Rust toolchain if building from source.

Verify before relying:

- Whether the package provides a high-level convenience API or requires deep familiarity with AST and pattern syntax to be productive.
- Performance characteristics when searching or rewriting large codebases.
- Availability of pattern libraries or templates for common refactoring tasks.
- Concrete example of how to invoke the binding's main entry points after import.

## Package facts

- License: MIT (permissive)
- Python support: supports_current
- Install friction: medium
- Maintenance: active
- Downloads: 1.2M/month (top 5,000 on PyPI)
- Known vulnerabilities: none known

## Tags

ast pattern matching code search, structural code search and rewrite, ast-based codemod tool, code linting with ast patterns, large-scale code refactoring, syntax tree pattern matching, programmatic code analysis, code-search, ast-analysis, codemod

[View on SkillFed](https://skillfed.io/packages/ast-grep-py) · [View on PyPI](https://pypi.org/project/ast-grep-py/)