Installation

Install and set up Graph-sitter in your development environment.

​

We currently 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 for more details.
• Python, Typescript, Javascript and React codebases

​

Prerequisites

We recommend using uv for installation. If you haven’t installed uv yet:

curl -LsSf https://astral.sh/uv/install.sh | sh

​

Installing Codegen

uv tool install graph-sitter --python 3.13

​

Quick Start

Let’s walk through a minimal example of using Graph-sitter in a project:

1. Navigate to your repository:

   cd path/to/your/project
   

2. Initialize Graph-sitter in your project with gs init:

   gs init
   

   This creates a .codegen/ directory with:

   .codegen/
   ├── .venv/            # Python virtual environment (gitignored)
   ├── config.toml       # Project configuration
   ├── codemods/         # Your codemod implementations
   ├── jupyter/          # Jupyter notebooks for exploration
   └── codegen-system-prompt.txt  # AI system prompt
   

3. Create your first codemod with gs create:

   gs create organize-imports \
     -d "Sort and organize imports according to PEP8"
   

   The -d flag in gs create generates an AI-powered implementation. This requires a Github account registered on codegen.sh

4. Run your codemod with gs run:

   gs run organize-imports
   

5. Reset any filesystem changes (excluding .codegen/*) with gs reset:

   gs reset
   

​

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 'codegen.sdk.extensions.utils': The compiled cython extensions are out of sync. Update them with uv sync --reinstall-package codegen.
• 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).

​

Next Steps