Installation

Install and set up Codegen in your development environment.

We currently support:

• Running Codegen 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 codegen --python 3.13

This makes the codegen command available globally in your terminal, while keeping its dependencies isolated.

Quick Start

Let’s walk through a minimal example of using Codegen in a project:

1. Navigate to your repository:

   cd path/to/your/project
   

2. Initialize Codegen in your project with codegen init:

   codegen 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 codegen create:

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

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

4. Run your codemod with codegen run:

   codegen run organize-imports
   

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

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

For more help, join our community Slack or check the FAQ.

Next Steps

IDE Integration

Learn how to use Codegen 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 Codegen