Scriptable interface to a powerful, multi-lingual language server.
[](https://pypi.org/project/graph-sitter/)
[](https://graph-sitter.com)
[](https://community.codegen.com)
[](https://github.com/codegen-sh/graph-sitter/tree/develop?tab=Apache-2.0-1-ov-file)
[](https://x.com/codegen)
[Graph-sitter](https://graph-sitter.com) is a python library for manipulating codebases.
```python
from graph_sitter import Codebase
# Graph-sitter builds a complete graph connecting
# functions, classes, imports and their relationships
codebase = Codebase("./")
# Work with code without dealing with syntax trees or parsing
for function in codebase.functions:
# Comprehensive static analysis for references, dependencies, etc.
if not function.usages:
# Auto-handles references and imports to maintain correctness
function.move_to_file("deprecated.py")
```
Write code that transforms code. Graph-sitter combines the parsing power of [Tree-sitter](https://tree-sitter.github.io/tree-sitter/) with the graph algorithms of [rustworkx](https://github.com/Qiskit/rustworkx) to enable scriptable, multi-language code manipulation at scale.
## Installation and Usage
We support
- Running Graph-sitter in Python 3.12 - 3.13 (recommended: Python 3.13+)
- macOS and Linux
- macOS is supported
- Linux is supported on x86_64 and aarch64 with glibc 2.34+
- Windows is supported via WSL. See [here](https://graph-sitter.com/building-with-graph-sitter/codegen-with-wsl) for more details.
- Python, Typescript, Javascript and React codebases
```
# Install inside existing project
uv pip install graph-sitter
# Install global CLI
uv tool install graph-sitter --python 3.13
# Create a codemod for a given repo
cd path/to/repo
gs init
gs create test-function
# Run the codemod
gs run test-function
# Create an isolated venv with graph-sitter => open jupyter
gs notebook
```
## Usage
See [Getting Started](https://graph-sitter.com/introduction/getting-started) for a full tutorial.
```
from graph_sitter import Codebase
```
## Troubleshooting
Having issues? Here are some common problems and their solutions:
- **I'm hitting an UV error related to `[[ packages ]]`**: This means you're likely using an outdated version of UV. Try updating to the latest version with: `uv self update`.
- **I'm hitting an error about `No module named 'graph_sitter.sdk.extensions.utils'`**: The compiled cython extensions are out of sync. Update them with `uv sync --reinstall-package graph-sitter`.
- **I'm hitting a `RecursionError: maximum recursion depth exceeded` error while parsing my codebase**: If you are using python 3.12, try upgrading to 3.13. If you are already on 3.13, try upping the recursion limit with `sys.setrecursionlimit(10000)`.
If you run into additional issues not listed here, please [join our slack community](https://community.codegen.com) and we'll help you out!
## Resources
- [Docs](https://graph-sitter.com)
- [Getting Started](https://graph-sitter.com/introduction/getting-started)
- [Contributing](CONTRIBUTING.md)
- [Contact Us](https://codegen.com/contact)
## Why Graph-sitter?
Software development is fundamentally programmatic. Refactoring a codebase, enforcing patterns, or analyzing control flow - these are all operations that can (and should) be expressed as programs themselves.
We built Graph-sitter backwards from real-world refactors performed on enterprise codebases. Instead of starting with theoretical abstractions, we focused on creating APIs that match how developers actually think about code changes:
- **Natural mental model**: Write transforms that read like your thought process - "move this function", "rename this variable", "add this parameter". No more wrestling with ASTs or manual import management.
- **Battle-tested on complex codebases**: Handle Python, TypeScript, and React codebases with millions of lines of code.
- **Built for advanced intelligences**: As AI developers become more sophisticated, they need expressive yet precise tools to manipulate code. Graph-sitter provides a programmatic interface that both humans and AI can use to express complex transformations through code itself.
## Contributing
Please see our [Contributing Guide](CONTRIBUTING.md) for instructions on how to set up the development environment and submit contributions.
## Enterprise
For more information on enterprise engagements, please [contact us](https://codegen.com/contact) or [request a demo](https://codegen.com/request-demo).