Installation

Graph-sitter runs as a single command with uvx — no global install or project setup required.

We currently support:

• Python 3.12 - 3.13 (recommended: Python 3.13+)
• macOS and Linux (x86_64 and aarch64 with glibc 2.34+); Windows via WSL
• Python, TypeScript, JavaScript, and React codebases

Prerequisites

Install uv if you don't already have it:

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

Run with uvx

uvx fetches and runs graph-sitter in an isolated environment, so there's nothing to install or keep up to date:

# Verify your environment
uvx --python 3.13 graph-sitter doctor --json
 
# Parse a repository into the codebase graph
uvx --python 3.13 graph-sitter parse . --language auto --backend auto --fallback python --format summary

Use --language typescript for TypeScript, JavaScript, and React repositories, or --language auto to let graph-sitter detect it.

Transform

Run a codemod in check mode, then write once the diff looks right:

uvx --python 3.13 graph-sitter transform ./codemods/rename.py:rename . --check
uvx --python 3.13 graph-sitter transform ./codemods/rename.py:rename . --write

Rust backend (optional)

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:

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

To validate a branch-built Rust wheel before a release, point uvx at the wheel artifact:

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.

Troubleshooting

• UV error related to [[ packages ]]: you're likely on an outdated UV. Update with uv self update.
• RecursionError: maximum recursion depth exceeded while parsing: upgrade to Python 3.13, or raise the limit with sys.setrecursionlimit(10000).

Next Steps