Skip to main content
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 Graph-sitter

uv tool install graph-sitter --python 3.13
This makes the graph-sitter command available globally in your terminal, while keeping its dependencies isolated.

​
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 '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).
For more help, join our community Slack or check the FAQ.

​
Next Steps

IDE Integration

Learn how to use Graph-sitter effectively in VSCode, Cursor, and other IDEs.

Tutorials

Follow step-by-step tutorials for common code transformation tasks.

Work with AI

Leverage AI assistants like Copilot, Cursor and Devin

Guides

Learn more about building with Graph-sitter
⌘I