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 Graph-sitter

uv tool install graph-sitter --python 3.13

Verify the installation before parsing a large repository:

graph-sitter doctor --json
graph-sitter parse . --language python --backend python --format summary

Use --language typescript for TypeScript, JavaScript, and React repositories.

One-Shot uvx Usage

Use uvx when you want to run Graph-sitter without installing a global tool:

uvx --python 3.13 graph-sitter doctor --json
uvx --python 3.13 graph-sitter parse . --language auto --backend auto --fallback python --format json

For branch-built Rust wheel validation before a public release, point uvx at the wheel artifact:

uvx --python 3.13 --from dist/<wheel>.whl graph-sitter doctor --backend rust --language python --json
uvx --python 3.13 --from dist/<wheel>.whl graph-sitter parse . --language python --backend rust --fallback error --format json

See uvx workflows for parse, run, transform, --subdir, and release-gate examples.

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. Parse the repository without initialization:

   graph-sitter parse . --language python --backend python --format summary

   For TypeScript, JavaScript, and React repositories:

   graph-sitter parse . --language typescript --backend auto --fallback python --format summary

3. Initialize Graph-sitter in your project with graph-sitter init:

   graph-sitter 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

4. Create your first codemod with graph-sitter create:

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

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

5. Preview your codemod with graph-sitter run:

   graph-sitter run organize-imports . --check

6. Apply the codemod after reviewing the diff:

   graph-sitter run organize-imports . --write

7. Reset any filesystem changes (excluding .codegen/*) with graph-sitter reset:

   graph-sitter reset

Rust Backend

Python remains the authoring shell. The Rust backend is an opt-in compact parse/index backend for supported graph and codemod surfaces.

Use strict Rust mode when unsupported behavior should fail loudly:

graph-sitter parse . --language python --backend rust --fallback error --format json

Use automatic mode with Python fallback when a working result is more important than proving the Rust path:

graph-sitter parse . --language auto --backend auto --fallback python --format json

Python API users can select the same backend behavior through CodebaseConfig:

from graph_sitter.configs.models.codebase import (
    CodebaseConfig,
    GraphBackend,
    RustFallbackMode,
)
from graph_sitter.core.codebase import Codebase
 
codebase = Codebase(
    "./",
    config=CodebaseConfig(
        graph_backend=GraphBackend.RUST,
        rust_fallback=RustFallbackMode.ERROR,
    ),
)

Run doctor before relying on strict Rust mode in CI, benchmarks, or release validation.

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).

Next Steps