Skip to content

Installation Guide

This guide will help you install and set up flujo for your project.

Prerequisites

  • Python 3.11 or higher
  • pip (Python package installer)
  • Virtual environment (recommended)

Basic Installation

The simplest way to install the package is using pip:

pip install flujo

Installation with Extras

The package includes several optional extras that provide additional functionality:

# For development (includes testing tools, linting, etc.)
pip install "flujo[dev]"

# For benchmarking (includes numpy for statistical analysis)
pip install "flujo[bench]"

# For documentation building
pip install "flujo[docs]"

# For OpenTelemetry support
pip install "flujo[opentelemetry]"

# For Logfire-based telemetry
pip install "flujo[logfire]"

# For the SQL syntax validator plugin
pip install "flujo[sql]"

# Install all extras
pip install "flujo[dev,docs,opentelemetry,logfire,sql,bench]"

Development Installation

For development work, you can install the package in editable mode:

# Clone the repository
git clone https://github.com/aandresalvarez/flujo.git
cd flujo

# Create and activate a virtual environment
python3.11 -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install in editable mode with development extras
pip install -e ".[dev]"

Environment Setup

  1. Copy the example environment file: 

    cp .env.example .env

  2. Add your API keys to .env: 

    # Required: At least one provider key
OPENAI_API_KEY=your_key_here
ANTHROPIC_API_KEY=your_key_here
GOOGLE_API_KEY=your_key_here

# Optional: Logfire for advanced telemetry
# LOGFIRE_API_KEY=your_logfire_key

# Optional: Configuration overrides
REFLECTION_ENABLED=true
REWARD_ENABLED=false
AGENT_TIMEOUT=60
TELEMETRY_EXPORT_ENABLED=false

# Optional: Model overrides
DEFAULT_SOLUTION_MODEL=openai:gpt-4o
DEFAULT_REVIEW_MODEL=openai:gpt-4o
DEFAULT_VALIDATOR_MODEL=openai:gpt-4o
DEFAULT_REFLECTION_MODEL=openai:gpt-4o
DEFAULT_SELF_IMPROVEMENT_MODEL=openai:gpt-4o

Verifying Installation

To verify your installation:

# Check version
flujo version-cmd

# Test basic functionality
flujo solve "Write a hello world function in Python"

# Show current configuration
flujo show-config

You can also verify programmatically:

import flujo
print(f"Version: {flujo.__version__}")

# Test basic import
from flujo.recipes.factories import make_default_pipeline
from flujo import Task
print("✅ Installation successful!")

Troubleshooting

Common Issues

  1. Python Version Error
  2. Ensure you're using Python 3.11 or higher

  3. Check with: python --version

  4. Missing Dependencies

  5. Try reinstalling with: pip install --upgrade flujo

  6. For development: pip install -e ".[dev]"

  7. API Key Issues

  8. Verify your .env file exists and contains valid API keys
  9. Check that the keys are properly formatted

  10. Ensure at least one provider key (OpenAI, Anthropic, or Google) is set

  11. Import Errors

  12. Make sure you're in the correct virtual environment

  13. Try: pip list | grep flujo

  14. Permission Errors

  15. On Unix systems, you might need: pip install --user flujo
  16. Or use a virtual environment (recommended)

Getting Help

If you encounter any issues: 1. Check the troubleshooting guide 2. Search existing issues 3. Create a new issue if needed

Next Steps