233 lines
7.1 KiB
Text
233 lines
7.1 KiB
Text
---
|
|
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="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
|