---
title: "Python Installation"
description: "Install and configure Codeflash for your Python project in minutes"
icon: "python"
sidebarTitle: "Python Setup"
---

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="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 (or login with Codeflash)
2. Which Python module do you want me to optimize going forward? (e.g. my_module)
3. Where are your tests located? (e.g. tests/)
4. Which code formatter do you use? (black/ruff/other/disabled)
5. Which git remote should Codeflash use for Pull Requests? (if multiple remotes exist)
6. Help us improve Codeflash by sharing anonymous usage data?
7. Install the GitHub app
8. Install GitHub actions for Continuous optimization?
```

After you have answered these questions, the Codeflash configuration will be saved in the `pyproject.toml` file.

</Step>

<Step title="Generate a Codeflash API Key">
Codeflash uses cloud-hosted AI models and integrations with GitHub. If you haven't created one already, you'll need to create 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="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.

</Step>

</Steps>

To understand the configuration options, and set more advanced options, see the [Manual Configuration](/configuration) page.

## 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
