🧬 The most advanced open-source evolutionary coding agent

Turn your LLMs into autonomous code optimizers that discover breakthrough algorithms

🚀 Quick Start • Examples • System Messages • Discussions

From random search to state-of-the-art: Watch your code evolve in real-time

OpenEvolve vs Manual Optimization:

Get from zero to evolving code in 30 seconds:

# Install OpenEvolve
pip install openevolve

# The example uses Google Gemini by default (free tier available)
# Get your API key from: https://aistudio.google.com/apikey
export OPENAI_API_KEY="your-gemini-api-key"  # Yes, use OPENAI_API_KEY env var

# Run your first evolution!
python openevolve-run.py examples/function_minimization/initial_program.py \
  examples/function_minimization/evaluator.py \
  --config examples/function_minimization/config.yaml \
  --iterations 50

Note: The example config uses Gemini by default, but you can use any OpenAI-compatible provider by modifying the config.yaml. See the configs for full configuration options.

OpenEvolve can be used as a library without any external files:

from openevolve import run_evolution, evolve_function

# Evolution with inline code (no files needed!)
result = run_evolution(
    initial_program='''
    def fibonacci(n):
        if n <= 1: return n
        return fibonacci(n-1) + fibonacci(n-2)
    ''',
    evaluator=lambda path: {"score": benchmark_fib(path)},
    iterations=100
)

# Evolve Python functions directly
def bubble_sort(arr):
    for i in range(len(arr)):
        for j in range(len(arr)-1):
            if arr[j] > arr[j+1]:
                arr[j], arr[j+1] = arr[j+1], arr[j] 
    return arr

if __name__ == '__main__':
    result = evolve_function(
        bubble_sort,
        test_cases=[([3,1,2], [1,2,3]), ([5,2,8], [2,5,8])],
        iterations=50
    )
    print(f"Evolved sorting algorithm: {result.best_code}")

Note: On macOS and Windows, Python uses spawn for multiprocessing. You must wrap evolution calls in if __name__ == '__main__': to avoid subprocess bootstrap errors. To experiment with island scheduling, pass an optional selector to run_evolution:

def select_island(context):
    # Schedule the next iteration on the island with the fewest pending tasks.
    return min(range(len(context.islands)), key=lambda i: context.pending_counts[i])

result = run_evolution(
    initial_program="program.py",
    evaluator="evaluator.py",
    island_selector=select_island,
)

The selector receives a read-only IslandSelectionContext with the iteration number, pending task counts, and each island's population size, best and average score, diversity, and generation. It must return an island ID from 0 to num_islands - 1. It runs in the main process before each iteration is submitted. Without a selector, OpenEvolve uses its existing balanced island scheduling.

Population management can also use decision hooks. For example, this policy lets a candidate replace an island's MAP-Elites cell occupant when their scores tie:

from openevolve import run_evolution
from openevolve.population import PopulationStrategy

strategy = PopulationStrategy(
    replace_cell=lambda state, candidate, incumbent, island: (
        candidate.metrics["combined_score"] >= incumbent.metrics["combined_score"]
    ),
)
result = run_evolution("program.py", "evaluator.py", population_strategy=strategy)

Other optional hooks are admit(state, candidate, island) -> bool, archive(state, candidate) -> ArchiveDecision, evict(state, count, protected_ids) -> sequence of program IDs, migration_due(state) -> bool, and migrate(state) -> sequence of MigrationMove. state is a detached PopulationSnapshot of programs, island memberships, cell owners, the archive, population limits, and migration generations. Unspecified hooks retain the existing rules. ProgramDatabase validates decisions and applies all changes; the strategy never receives the mutable database. The initial seed cannot be rejected.

Prefer Docker? See the Installation & Setup section for Docker options.

Watch OpenEvolve discover optimal circle packing in real-time:

Generation 1	Generation 190	Generation 460 (Final)
Random placement	Learning structure	State-of-the-art result

Result: Matches published benchmarks for n=26 circle packing problem.

Before (Baseline):

// Standard attention implementation
kernel void attention_baseline(/* ... */) {
    // Generic matrix multiplication
    float sum = 0.0;
    for (int i = 0; i < seq_len; i++) {
        sum += query[tid] * key[i];
    }
}

After Evolution (2.8x faster):

// OpenEvolve discovered optimization
kernel void attention_evolved(/* ... */) {
    // Hardware-aware tiling + unified memory optimization
    threadgroup float shared_mem[256];
    // ... evolved algorithm exploiting Apple Silicon architecture
}

Performance Impact: 2.8x speedup on Apple M1 Pro, maintaining numerical accuracy.

OpenEvolve implements a sophisticated evolutionary coding pipeline that goes far beyond simple optimization:

• Quality-Diversity Evolution: Maintains diverse populations across feature dimensions
• Island-Based Architecture: Multiple populations prevent premature convergence
• LLM Ensemble: Multiple models with intelligent fallback strategies
• Artifact Side-Channel: Error feedback improves subsequent generations

• Comprehensive Seeding: Every component (LLM, database, evaluation) is seeded
• Default Seed=42: Immediate reproducible results out of the box
• Deterministic Evolution: Exact reproduction of runs across machines
• Component Isolation: Hash-based isolation prevents cross-contamination

• Universal API: Works with OpenAI, Google, Claude Code CLI, local models, and proxies
• Intelligent Ensembles: Weighted combinations with sophisticated fallback
• Test-Time Compute: Enhanced reasoning through proxy systems (see OptiLLM setup)
• Plugin Ecosystem: Support for advanced reasoning plugins

• Double Selection: Different programs for performance vs inspiration
• Adaptive Feature Dimensions: Custom quality-diversity metrics
• Migration Patterns: Ring topology with controlled gene flow
• Multi-Strategy Sampling: Elite, diverse, and exploratory selection

• Python: 3.10+
• LLM Access: Any OpenAI-compatible API, or Claude Code CLI
• Optional: Docker for containerized runs

pip install openevolve

git clone https://github.com/algorithmicsuperintelligence/openevolve.git
cd openevolve
pip install -e ".[dev]"

# Pull the image
docker pull ghcr.io/algorithmicsuperintelligence/openevolve:latest

# Run an example
docker run --rm -v $(pwd):/app ghcr.io/algorithmicsuperintelligence/openevolve:latest \
  examples/function_minimization/initial_program.py \
  examples/function_minimization/evaluator.py --iterations 100

Cost depends on your LLM provider and iterations:

• o3: ~$0.15-0.60 per iteration (depending on code size)
• o3-mini: ~$0.03-0.12 per iteration (more cost-effective)
• Gemini-2.5-Pro: ~$0.08-0.30 per iteration
• Gemini-2.5-Flash: ~$0.01-0.05 per iteration (fastest and cheapest)
• Local models: Nearly free after setup
• OptiLLM: Use cheaper models with test-time compute for better results

Cost-saving tips:

• Start with fewer iterations (100-200)
• Use o3-mini, Gemini-2.5-Flash or local models for exploration
• Use cascade evaluation to filter bad programs early
• Configure smaller population sizes initially

OpenEvolve works with any OpenAI-compatible API:

export OPENAI_API_KEY="sk-..."
# Uses OpenAI endpoints by default

# config.yaml
llm:
  api_base: "https://generativelanguage.googleapis.com/v1beta/openai/"
  model: "gemini-2.5-pro"

export OPENAI_API_KEY="your-gemini-api-key"

# config.yaml
llm:
  api_base: "http://localhost:11434/v1"  # Ollama
  model: "codellama:7b"

For maximum flexibility with rate limiting, model routing, and test-time compute:

# Install OptiLLM
pip install optillm

# Start OptiLLM proxy
optillm --port 8000

# Point OpenEvolve to OptiLLM
export OPENAI_API_KEY="your-actual-key"

llm:
  api_base: "http://localhost:8000/v1"
  model: "moa&readurls-o3"  # Test-time compute + web access

Use the Claude Code CLI as the LLM backend — no API keys needed, authentication uses the CLI's OAuth session.

# Install and authenticate
npm install -g @anthropic-ai/claude-code
claude login

# config.yaml
llm:
  provider: "claude_code"
  models:
    - name: "sonnet"
      weight: 0.8
      max_tokens: 16000
      max_budget_usd: 1.0
    - name: "haiku"
      weight: 0.2
      max_tokens: 8000

See the Claude Code quickstart example for a complete walkthrough.

Use the GitHub Copilot CLI as the LLM backend — no API keys needed, authentication uses your GitHub Copilot subscription.

# Install and authenticate
npm install -g @github/copilot
copilot login

# config.yaml
llm:
  provider: "copilot_cli"
  models:
    - name: "claude-sonnet-4.6"
      weight: 0.8
      reasoning_effort: "medium"
    - name: "gpt-5.4"
      weight: 0.2

See the Copilot CLI quickstart example for a complete walkthrough.

Watch OpenEvolve evolve from random search to sophisticated optimization:

# Initial Program (Random Search)
def minimize_function(func, bounds, max_evals=1000):
    best_x, best_val = None, float('inf')
    for _ in range(max_evals):
        x = random_point_in_bounds(bounds)
        val = func(x)
        if val < best_val:
            best_x, best_val = x, val
    return best_x, best_val

Evolution Process

# Evolved Program (Simulated Annealing + Adaptive Cooling)
def minimize_function(func, bounds, max_evals=1000):
    x = random_point_in_bounds(bounds)
    temp = adaptive_initial_temperature(func, bounds)
    
    for i in range(max_evals):
        neighbor = generate_neighbor(x, temp, bounds)
        delta = func(neighbor) - func(x)
        
        if delta < 0 or random.random() < exp(-delta/temp):
            x = neighbor
            
        temp *= adaptive_cooling_rate(i, max_evals)  # Dynamic cooling
    
    return x, func(x)

Performance: 100x improvement in convergence speed!

Evolve prompts instead of code for better LLM performance. See the LLM Prompt Optimization example for a complete case study with HotpotQA achieving +23% accuracy improvement.

Full Example

Automatic solution generation for programming contests:

# Problem: Find maximum subarray sum
# OpenEvolve discovers multiple approaches:

# Evolution Path 1: Brute Force → Kadane's Algorithm
# Evolution Path 2: Divide & Conquer → Optimized Kadane's
# Evolution Path 3: Dynamic Programming → Space-Optimized DP

Online Judge Integration

OpenEvolve offers extensive configuration for advanced users:

# Advanced Configuration Example
max_iterations: 1000
random_seed: 42  # Full reproducibility

llm:
  # Ensemble configuration
  models:
    - name: "gemini-2.5-pro"
      weight: 0.6
    - name: "gemini-2.5-flash"
      weight: 0.4
  temperature: 0.7

database:
  # MAP-Elites quality-diversity
  population_size: 500
  num_islands: 5  # Parallel evolution
  migration_interval: 20
  feature_dimensions: ["complexity", "diversity", "performance"]

  # Optional novelty filtering with Gemini embeddings
  embedding_model: "gemini-embedding-001"
  similarity_threshold: 0.99
  # Or any OpenAI-compatible embedding endpoint (OpenRouter, local servers):
  # embedding_api_base: "https://openrouter.ai/api/v1"  # or OPENAI_EMBEDDING_BASE_URL

evaluator:
  enable_artifacts: true      # Error feedback to LLM
  cascade_evaluation: true    # Multi-stage testing
  use_llm_feedback: true      # AI code quality assessment

prompt:
  # Sophisticated inspiration system
  num_top_programs: 3         # Best performers
  num_diverse_programs: 2     # Creative exploration
  include_artifacts: true     # Execution feedback
  
  # Custom templates
  template_dir: "custom_prompts/"
  use_template_stochasticity: true  # Randomized prompts

For Gemini embeddings, set GEMINI_API_KEY. GOOGLE_API_KEY is also supported as a fallback. OpenEvolve uses Google's OpenAI-compatible endpoint automatically.

Control how programs are organized in the quality-diversity grid:

database:
  feature_dimensions: 
    - "complexity"      # Built-in: code length
    - "diversity"       # Built-in: structural diversity
    - "performance"     # Custom: from your evaluator
    - "memory_usage"    # Custom: from your evaluator
    
  feature_bins:
    complexity: 10      # 10 complexity levels
    performance: 20     # 20 performance buckets
    memory_usage: 15    # 15 memory usage categories

Important: Return raw values from evaluator, OpenEvolve handles binning automatically.

Advanced prompt engineering with custom templates:

prompt:
  template_dir: "custom_templates/"
  use_template_stochasticity: true
  template_variations:
    greeting:
      - "Let's enhance this code:"
      - "Time to optimize:"
      - "Improving the algorithm:"
    improvement_suggestion:
      - "Here's how we could improve this code:"
      - "I suggest the following improvements:"
      - "We can enhance this code by:"

How it works: Place {greeting} or {improvement_suggestion} placeholders in your templates, and OpenEvolve will randomly choose from the variations for each generation, adding diversity to prompts.

See prompt examples for complete template customization.

System messages are the secret to successful evolution. They guide the LLM's understanding of your domain, constraints, and optimization goals. A well-crafted system message can be the difference between random mutations and targeted improvements.

The system message in your config.yaml is arguably the most important component for evolution success:

• Domain Expertise: Provides LLM with specific knowledge about your problem space
• Constraint Awareness: Defines what can and cannot be changed during evolution
• Optimization Focus: Guides the LLM toward meaningful improvements
• Error Prevention: Helps avoid common pitfalls and compilation errors

Based on successful OpenEvolve implementations, system messages are best created through iteration:

Phase 1: Initial Draft

1. Start with a basic system message describing your goal
2. Run 20-50 evolution iterations to observe behavior
3. Note where the system gets "stuck" or makes poor choices

Phase 2: Refinement

4. Add specific guidance based on observed issues
5. Include domain-specific terminology and concepts
6. Define clear constraints and optimization targets
7. Run another batch of iterations

Phase 3: Specialization

8. Add detailed examples of good vs bad approaches
9. Include specific library/framework guidance
10. Add error avoidance patterns you've observed
11. Fine-tune based on artifact feedback

Phase 4: Optimization

12. Consider using OpenEvolve itself to optimize your prompt
13. Measure improvements using combined score metrics

prompt:
  system_message: |
    You are an expert programmer specializing in optimization algorithms.
    Your task is to improve a function minimization algorithm to find the
    global minimum reliably, escaping local minima that might trap simple algorithms.

prompt:
  system_message: |
    You are an expert prompt engineer. Your task is to revise prompts for LLMs.

    Your improvements should:
    * Clarify vague instructions and eliminate ambiguity
    * Strengthen alignment between prompt and desired task outcome
    * Improve robustness against edge cases
    * Include formatting instructions and examples where helpful
    * Avoid unnecessary verbosity

    Return only the improved prompt text without explanations.

prompt:
  system_message: |
    You are an expert Metal GPU programmer specializing in custom attention
    kernels for Apple Silicon.

    # TARGET: Optimize Metal Kernel for Grouped Query Attention (GQA)
    # HARDWARE: Apple M-series GPUs with unified memory architecture
    # GOAL: 5-15% performance improvement

    # OPTIMIZATION OPPORTUNITIES:
    **1. Memory Access Pattern Optimization:**
    - Coalesced access patterns for Apple Silicon
    - Vectorized loading using SIMD
    - Pre-compute frequently used indices

    **2. Algorithm Fusion:**
    - Combine max finding with score computation
    - Reduce number of passes through data

    # CONSTRAINTS - CRITICAL SAFETY RULES:
    **MUST NOT CHANGE:**
    ❌ Kernel function signature
    ❌ Template parameter names or types
    ❌ Overall algorithm correctness

    **ALLOWED TO OPTIMIZE:**
    ✅ Memory access patterns and indexing
    ✅ Computation order and efficiency
    ✅ Vectorization and SIMD utilization
    ✅ Apple Silicon specific optimizations

Structure Your Message: Start with role definition → Define task/context → List optimization opportunities → Set constraints → Success criteria

Use Specific Examples:

# Good: "Focus on reducing memory allocations. Example: Replace `new Vector()` with pre-allocated arrays."
# Avoid: "Make the code faster"

Include Domain Knowledge:

# Good: "For GPU kernels: 1) Memory coalescing 2) Occupancy 3) Shared memory usage"
# Avoid: "Optimize the algorithm"

Set Clear Boundaries:

system_message: |
  MUST NOT CHANGE: ❌ Function signatures ❌ Algorithm correctness ❌ External API
  ALLOWED: ✅ Internal implementation ✅ Data structures ✅ Performance optimizations

Artifact-Driven Iteration: Enable artifacts in config → Include common error patterns in system message → Add guidance based on stderr/warning patterns

Multi-Phase Evolution: Start broad ("Explore different algorithmic approaches"), then focus ("Given successful simulated annealing, focus on parameter tuning")

Template Stochasticity: See the Configuration section for complete template variation examples.

You can use OpenEvolve to evolve your system messages themselves! This powerful technique lets you optimize prompts for better LLM performance automatically.

See the LLM Prompt Optimization example for a complete implementation, including the HotpotQA case study with +23% accuracy improvement.

• Too Vague: "Make the code better" → Specify exactly what "better" means
• Too Restrictive: Over-constraining can prevent useful optimizations
• Missing Context: Include relevant domain knowledge and terminology
• No Examples: Concrete examples guide LLM better than abstract descriptions
• Ignoring Artifacts: Don't refine prompts based on error feedback

Artifacts side-channel provides rich feedback to accelerate evolution:

# Evaluator can return execution context
from openevolve.evaluation_result import EvaluationResult

return EvaluationResult(
    metrics={"performance": 0.85, "correctness": 1.0},
    artifacts={
        "stderr": "Warning: suboptimal memory access pattern",
        "profiling_data": {...},
        "llm_feedback": "Code is correct but could use better variable names",
        "build_warnings": ["unused variable x"]
    }
)

Next generation prompt automatically includes:

## Previous Execution Feedback
⚠️ Warning: suboptimal memory access pattern
💡 LLM Feedback: Code is correct but could use better variable names
🔧 Build Warnings: unused variable x

This creates a feedback loop where each generation learns from previous mistakes!

Real-time evolution tracking with interactive web interface:

# Install visualization dependencies
pip install -r scripts/requirements.txt

# Launch interactive visualizer
python scripts/visualizer.py

# Or visualize specific checkpoint
python scripts/visualizer.py --path examples/function_minimization/openevolve_output/checkpoints/checkpoint_100/

Features:

• 🌳 Evolution tree with parent-child relationships
• 📈 Performance tracking across generations
• 🔍 Code diff viewer showing mutations
• 📊 MAP-Elites grid visualization
• 🎯 Multi-metric analysis with custom dimensions

• Multi-Modal Evolution: Images, audio, and text simultaneously
• Federated Learning: Distributed evolution across multiple machines
• AutoML Integration: Hyperparameter and architecture evolution
• Benchmark Suite: Standardized evaluation across domains

• Self-Modifying Prompts: Evolution modifies its own prompting strategy
• Cross-Language Evolution: Python → Rust → C++ optimization chains
• Neurosymbolic Reasoning: Combine neural and symbolic approaches
• Human-AI Collaboration: Interactive evolution with human feedback

Want to contribute? Check out our roadmap discussions!

See the Cost Estimation section in Installation & Setup for detailed pricing information and cost-saving tips.

OpenEvolve shines when you need to explore large solution spaces or optimize for multiple objectives simultaneously.

Yes! OpenEvolve supports any OpenAI-compatible API:

• Commercial: OpenAI, Google, Cohere
• Local: Ollama, vLLM, LM Studio, text-generation-webui
• Advanced: OptiLLM for routing and test-time compute

Just set the api_base in your config to point to your endpoint.

Built-in mechanisms prevent stagnation:

• Island migration: Fresh genes from other populations
• Temperature control: Exploration vs exploitation balance
• Diversity maintenance: MAP-Elites prevents convergence
• Artifact feedback: Error messages guide improvements
• Template stochasticity: Randomized prompts break patterns

Manual interventions:

• Increase num_diverse_programs for more exploration
• Add custom feature dimensions to diversify search
• Use template variations to randomize prompts
• Adjust migration intervals for more cross-pollination

Multiple success metrics:

1. Primary Metric: Your evaluator's combined_score or metric average
2. Convergence: Best score improvement over time
3. Diversity: MAP-Elites grid coverage
4. Efficiency: Iterations to reach target performance
5. Robustness: Performance across different test cases

Use the visualizer to track all metrics in real-time and identify when evolution has converged.

Thanks to all our amazing contributors who make OpenEvolve possible!

We welcome contributions! Here's how to get started:

1. 🍴 Fork the repository
2. 🌿 Create your feature branch: git checkout -b feat-amazing-feature
3. ✨ Add your changes and tests
4. ✅ Test everything: python -m unittest discover tests
5. 📝 Commit with a clear message
6. 🚀 Push and create a Pull Request

New to open source? Check out our Contributing Guide and look for good-first-issue labels!

Articles & Blog Posts About OpenEvolve:

• Towards Open Evolutionary Agents - Evolution of coding agents and the open-source movement
• OpenEvolve: GPU Kernel Discovery - Automated discovery of optimized GPU kernels
• OpenEvolve: Evolutionary Coding with LLMs - Introduction to evolutionary algorithm discovery using large language models

If you use OpenEvolve in your research, please cite:

@software{openevolve,
  title = {OpenEvolve: an open-source evolutionary coding agent},
  author = {Asankhaya Sharma},
  year = {2025},
  publisher = {GitHub},
  url = {https://github.com/algorithmicsuperintelligence/openevolve}
}