OpenEvolve Documentation

You can install OpenEvolve via PyPI for standard use, or via a development install if you are contributing to the repository. For containerized environments, use the official Docker image.

# PyPI (Recommended)
pip install openevolve

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

# Docker
docker pull ghcr.io/algorithmicsuperintelligence/openevolve:latest

OpenEvolve uses YAML configuration files to define evolution parameters. You can use configs/default_config.yaml as a template, as it contains all available options, default values, and documentation for all parameters.

To set up your own configuration, copy the default template and modify it to suit your needs:

cp configs/default_config.yaml my_config.yaml
# Edit my_config.yaml for your specific needs

OpenEvolve provides a real-time evolution tracking tool. You must first install the visualization dependencies, then you can launch the interactive visualizer or point it to a specific checkpoint directory to view the evolution tree, performance tracking, code diffs, and MAP-Elites grids.

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

OpenEvolve supports any OpenAI-compatible API. You can configure the api_base and model in your config.yaml.

Google Gemini

To use Gemini, set the api_base to the Google OpenAI-compatible endpoint and export your key as OPENAI_API_KEY.

Local Models (Ollama/vLLM)

Point the api_base to your local server address.

OptiLLM

For advanced routing and test-time compute, run the OptiLLM proxy and point OpenEvolve to its local port.

# Example Gemini configuration
llm:
  api_base: "https://generativelanguage.googleapis.com/v1beta/openai/"
  model: "gemini-2.5-pro"

# Example Local Model (Ollama)
llm:
  api_base: "http://localhost:11434/v1"
  model: "codellama:7b"

# Example OptiLLM
llm:
  api_base: "http://localhost:8000/v1"
  model: "moa&readurls-o3"

You can control how programs are organized in the quality-diversity grid by defining feature_dimensions and feature_bins under the database section.

Supported built-in dimensions:

• complexity: Based on code length.
• diversity: Based on structural diversity.
• performance: Custom dimension derived from your evaluator.

Note: Your evaluator must return raw values; OpenEvolve handles the binning into categories automatically.

database:
  feature_dimensions: 
    - "complexity"
    - "diversity"
    - "performance"
    - "memory_usage"
    
  feature_bins:
    complexity: 10
    performance: 20
    memory_usage: 15

To increase diversity in prompts, you can use custom templates with placeholders. Placeholders like {greeting} or {improvement_suggestion} are replaced by random variations defined in your configuration.

Set use_template_stochasticity: true and provide a template_dir to enable this feature.

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:"

You can use the Claude Code CLI as a backend, which allows for authentication via OAuth without needing an explicit API key. In your config.yaml, set the provider to claude_code and define a list of models with their respective weights and budgets.

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

The database supports a two-stage novelty check to prevent redundant evolution:

1. Embedding Similarity: It computes the cosine similarity between the new program's code embedding and existing program embeddings. If the similarity exceeds similarity_threshold, the program is considered potentially non-novel.
2. LLM Judgment: If a similar program is found, the system calls an LLM (via novelty_llm) to judge if the new code is actually novel compared to the existing code. The LLM must respond with NOVEL or NOT NOVEL.

If the LLM check fails or returns an empty response, the system defaults to assuming the program is novel.