codeflash/docs/getting-started/local-installation.mdx

---
title: "Local Installation"
description: "Install and configure Codeflash for your Python project in minutes"
icon: "download"
---

Codeflash is installed and configured on a per-project basis.

### Prerequisites

Before installing Codeflash, ensure you have:

1. **Python 3.9 or above** installed
2. **A Python project** with a virtual environment
3. **Project dependencies installed** in your virtual environment

Good to have (optional):
1. **Unit Tests** that Codeflash uses to ensure correctness of the optimizations

<Warning>
**Virtual Environment Required**

Always install Codeflash in your project's virtual environment, not globally. Make sure your virtual environment is activated before proceeding.

```bash
source venv/bin/activate  # On Linux/Mac
# or
venv\Scripts\activate     # On Windows
```
</Warning>
<Steps>
<Step title="Install Codeflash">

You can install Codeflash locally for a project by running the following command in the project's virtual environment:
```bash
pip install codeflash
```

<Tip>
**Codeflash is a Development Dependency**

We recommend installing Codeflash as a development dependency.
Codeflash is intended to be used in development workflows locally and as part of CI.
Try to always use the latest version of Codeflash as it improves quickly.

<CodeGroup>
```bash uv
uv add --dev codeflash
```

```bash poetry
poetry add codeflash@latest --group dev
```
</CodeGroup>
</Tip>
</Step>

<Step title="Generate a Codeflash API Key">
Codeflash uses cloud-hosted AI models and integrations with GitHub. You'll need an API key to authorize your access.

1. Visit the [Codeflash Web App](https://app.codeflash.ai/)
2. Sign up with your GitHub account (free)
3. Navigate to the [API Key](https://app.codeflash.ai/app/apikeys) page to generate your API key

<Note>
**Free Tier Available**

Codeflash offers a **free tier** with a limited number of optimizations. Perfect for trying it out on small projects!
</Note>
</Step>

<Step title="Run Automatic Configuration">
Navigate to your project's root directory (where your `pyproject.toml` file is or should be) and run:

```bash
codeflash init
```

If you don't have a pyproject.toml file yet, the codeflash init command will ask you to create one

<Info>
**What's pyproject.toml?**

`pyproject.toml` is a configuration file that is used to specify build and tool settings for Python projects.
`pyproject.toml` is the modern replacement for setup.py and requirements.txt files.
</Info>

When running `codeflash init`, you will see the following prompts:

```text
1. Enter your Codeflash API key:
2. Install the GitHub app.
3. Which Python module do you want me to optimize going forward? (e.g. my_module)
4. Where are your tests located? (e.g. tests/)
5. Which test framework do you use? (pytest/unittest)
6. Install GitHub actions for Continuous optimization?
```
</Step>
</Steps>

After you have answered these questions, the Codeflash configuration will be saved in the `pyproject.toml` file.
To understand the configuration options, and set more advanced options, see the [Manual Configuration](/configuration) page.

### Step 4: Install the Codeflash GitHub App

{/* TODO: Justify to users Why we need the user to install Github App even in local Installation or local optimization? */}
Finally, if you have not done so already, Codeflash will ask you to install the GitHub App in your repository.
The Codeflash GitHub App allows access to your repository to the codeflash-ai bot to open PRs, review code, and provide optimization suggestions.

Please [install the Codeflash GitHub
app](https://github.com/apps/codeflash-ai/installations/select_target) by choosing the repository you want to install
Codeflash on.

## Try It Out!

<Tabs>
<Tab title="Quick Start">
Once configured, you can start optimizing your code immediately:

```bash
# Optimize a specific function
codeflash --file path/to/your/file.py --function function_name

# Or optimize all functions in your codebase
codeflash --all
```

</Tab>

<Tab title="Optimize Example Project">
<Card title="🚀 Try optimizing our example repository" icon="github" href="https://github.com/codeflash-ai/optimize-me">
  Want to see Codeflash in action and don't know what code to optimize? Check out our **optimize-me** repository with code ready to optimize.
  
  **What's included:**
  - Sample Python code with performance issues
  - Tests for verification  
  - Pre-configured `pyproject.toml`
</Card>

<Steps>
  <Step title="Fork the Repository">
    Fork the [optimize-me](https://github.com/codeflash-ai/optimize-me) repo to your GitHub account by clicking "Fork" on the top of the page. This allows Codeflash to open Pull Requests with the optimizations it found on your forked repo.
  </Step>
<Step title="Clone the Forked Repository">
```bash
git clone https://github.com/your_github_username/optimize-me.git
cd optimize-me
```
</Step>

<Step title="Set Up Environment">
```bash
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
pip install codeflash
```
</Step>

<Step title="Run Codeflash">
```bash
codeflash init  # Use your own API key
codeflash --all # optimize the entire repo
```
</Step>
</Steps>
</Tab>
</Tabs>

## Troubleshooting

<AccordionGroup>
  <Accordion title="📦 Module not found errors">
    Make sure:
    - ✅ Your virtual environment is activated
    - ✅ All project dependencies are installed
    
    ```bash
    # Verify your virtual environment is active
    which python  # Should show path to your venv
    
    # Install missing dependencies
    pip install -r requirements.txt
    ```
  </Accordion>

  <Accordion title="🧪 No optimizations found or debugging issues">
    Do know that not all functions can be optimized as no optimization opportunities may exist for them. This is fine and expected.

    To investigate further, use the `--verbose` flag for detailed output:
    ```bash
    codeflash optimize --verbose
    ```
    
    This will show:
    - 🔍 Which functions are being analyzed
    - 🚫 Why certain functions were skipped
    - ⚠️ Detailed error messages
    - 📊 Performance analysis results

  </Accordion>

  <Accordion title="🔍 No tests found errors">
    Verify:
    - 📁 Your test directory path is correct in `pyproject.toml`
    - 🔍 Tests are discoverable by your test framework
    - 📝 Test files follow naming conventions (`test_*.py` for pytest)
    
    ```bash
    # Test if pytest can discover your tests
    pytest --collect-only
    
    # Check your pyproject.toml configuration
    cat pyproject.toml | grep -A 8 "\[tool.codeflash\]"
    ```
  </Accordion>
</AccordionGroup>


### Next Steps

- Learn about [Codeflash Concepts](/codeflash-concepts/how-codeflash-works)
- Explore [Optimization workflows](/optimizing-with-codeflash/one-function)
- Set up [Pull Request Optimization](/optimizing-with-codeflash/codeflash-github-actions)
- Read [configuration options](/configuration) for advanced setups