Installation

Install SkyDiscover and configure your development environment

System Requirements

Required

• Python: 3.10, 3.11, 3.12, or 3.13
• Operating System: Linux, macOS, or Windows (with WSL)
• Memory: 4GB RAM minimum (8GB+ recommended for large benchmarks)
• Disk Space: 2GB for base installation, additional space for benchmark data

Recommended

• uv: Fast Python package installer (installation guide)
• Git: For cloning the repository and managing checkpoints
• API Access: OpenAI, Google Gemini, Anthropic, or local LLM endpoint

Installation Methods

Method 1: Using uv (Recommended)

The fastest way to get started:

1. Install uv

   If you don’t have uv installed:

   # macOS/Linux
   curl -LsSf https://astral.sh/uv/install.sh | sh
   
   # Windows (PowerShell)
   powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
   
2. Clone the repository

   git clone https://github.com/sky-discover/skydiscover.git
   cd skydiscover
   
3. Install SkyDiscover

   uv sync
   

   This installs the base package with core dependencies:

   • openai>=1.0.0
   • pyyaml>=6.0
   • tqdm>=4.64.0
   • numpy>=1.22.0
4. Verify installation

   uv run skydiscover-run --help
   

   You should see the CLI help message.

Method 2: Using pip

Alternative installation with pip:

# Clone the repository
git clone https://github.com/sky-discover/skydiscover.git
cd skydiscover

# Create a virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install
pip install -e .

Installing Extras

SkyDiscover uses optional dependency groups for different benchmarks and features:

Math Benchmarks

For circle packing, Erdos problems, and geometric optimization:

uv sync --extra math

Installs: scipy, sympy, jax, optax, torch, scikit-learn, numba, pandas, matplotlib, plotly, networkx, cvxpy, autograd, pymoo, PyWavelets

ADRS Systems Benchmarks

For cloud scheduling and load balancing problems:

uv sync --extra adrs

Installs: numpy, pandas, networkx>=3.2,<3.4, torch

External Algorithm Backends

For OpenEvolve, GEPA, and ShinkaEvolve:

uv sync --extra external

Installs: openevolve, gepa[full], litellm>=1.81

ShinkaEvolve requires manual installation (see below).

Frontier-CS Benchmark

For competitive programming challenges:

uv sync --extra frontier-cs

Installs: anthropic, colorlog, datasets, google-genai, google-generativeai, numpy>=2.0.0, python-dotenv, skypilot

Frontier-CS requires numpy 2.x, which may conflict with other benchmarks using numpy 1.x. Use separate virtual environments if needed.

Prompt Optimization

For HotPotQA prompt evolution:

uv sync --extra prompt-optimization

Installs: dspy>=3.1.3, litellm, bm25s, pystemmer, datasets, diskcache, ujson

Development Tools

For contributors and developers:

uv sync --extra dev

Installs: pytest, pytest-asyncio, black, isort, mypy, requests

Combining Extras

Install multiple extras at once:

# Install math and external backends
uv sync --extra math --extra external

# Install everything for development
uv sync --extra dev --extra math --extra adrs --extra external

Manual Installation: ShinkaEvolve

ShinkaEvolve is not available on PyPI and requires manual installation:

# Clone ShinkaEvolve repository
git clone --depth 1 https://github.com/SakanaAI/ShinkaEvolve.git external_repos/ShinkaEvolve

# Install in your environment
uv pip install -e external_repos/ShinkaEvolve

Then use with:

uv run skydiscover-run initial_program.py evaluator.py \
  --search shinkaevolve \
  --iterations 100

Environment Variables

LLM API Keys

SkyDiscover automatically reads API keys from environment variables:

OpenAI

export OPENAI_API_KEY="sk-your-key-here"

Custom API Endpoints

For local or self-hosted LLMs:

# Using command-line flag
uv run skydiscover-run initial_program.py evaluator.py \
  --model ollama/llama3 \
  --api-base http://localhost:11434/v1 \
  --search adaevolve

# Or in config YAML

config.yaml

llm:
  api_base: http://localhost:11434/v1
  models:
    - name: ollama/llama3
      weight: 1.0

Other Environment Variables

# Set logging level (DEBUG, INFO, WARNING, ERROR)
export SKYDISCOVER_LOG_LEVEL=INFO

# Default output directory
export SKYDISCOVER_OUTPUT_DIR=./my_outputs

Verify Installation

Check Version

python -c "import skydiscover; print(skydiscover.__version__)"

Run Basic Test

Test your installation with a minimal example:

test_install.py

from skydiscover import discover_solution

def simple_evaluator(program_path):
    """Dummy evaluator for testing."""
    return {"combined_score": 1.0}

result = discover_solution(
    evaluator=simple_evaluator,
    initial_solution="def solve(x): return x",
    iterations=1,
    model="gpt-5",
)

print(f"Installation verified! Score: {result.best_score}")

python test_install.py

Model Configuration

Single Model

Use a single model for all generations:

uv run skydiscover-run initial_program.py evaluator.py \
  --model gpt-5 \
  --search adaevolve

Multiple Models with Weighted Sampling

Combine multiple models in a config file:

config.yaml

llm:
  models:
    - name: gpt-5
      weight: 0.7
    - name: gemini/gemini-2.0-flash
      weight: 0.3

SkyDiscover will randomly select models based on their weights for each generation.

Supported Model Providers

SkyDiscover supports any LiteLLM-compatible model:

OpenAI

--model gpt-5
--model gpt-4o
--model gpt-5-mini

Troubleshooting

Import Errors

ModuleNotFoundError: No module named 'scipy'

You’re trying to run a math benchmark without the math extras:

uv sync --extra math

ModuleNotFoundError: No module named 'openevolve'

You’re trying to use an external backend without installing it:

uv sync --extra external

ImportError: numpy version conflict

Frontier-CS requires numpy 2.x, which may conflict with other benchmarks:

# Option 1: Create separate environment for Frontier-CS
python -m venv venv-frontier-cs
source venv-frontier-cs/bin/activate
uv sync --extra frontier-cs

# Option 2: Override numpy version in pyproject.toml

API Key Issues

openai.error.AuthenticationError: Invalid API key

Ensure your API key is set correctly:

# Check if key is set
echo $OPENAI_API_KEY

# Set it if missing
export OPENAI_API_KEY="sk-your-key-here"

# Make it persistent (add to ~/.bashrc or ~/.zshrc)
echo 'export OPENAI_API_KEY="sk-your-key-here"' >> ~/.bashrc

Rate limit exceeded

OpenAI and other providers have rate limits. To handle this:

1. Reduce concurrency in your config:

config.yaml

llm:
  max_parallel_requests: 2  # Reduce from default

2. Add retry logic (built-in by default)

3. Use multiple models to distribute load:

config.yaml

llm:
  models:
    - name: gpt-5
      weight: 0.5
    - name: gemini/gemini-2.0-flash
      weight: 0.5

Performance Issues

Discovery is very slow

1. Use faster models:

   • Replace gpt-5 with gpt-5-mini or gemini/gemini-2.0-flash

2. Reduce timeout:

   evaluator:
     timeout: 60  # Reduce from default 360
   

3. Enable cascade evaluation (evaluates cheap checks first):

   evaluator:
     cascade_evaluation: true
     cascade_thresholds: [0.3, 0.6]
   

Out of memory errors

1. Reduce batch size or max solution length:

   max_solution_length: 30000  # Reduce from default 60000
   

2. Disable checkpointing (saves disk I/O):

   checkpoint_interval: null  # Disable checkpoints
   

3. Use a smaller database:

   database:
     max_programs: 1000  # Limit stored programs
   

Platform-Specific Issues

Windows: 'uv' is not recognized

Ensure uv is in your PATH:

# Reinstall uv
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

# Or add to PATH manually
$env:Path += ";$env:USERPROFILE\.cargo\bin"

macOS: SSL certificate errors

Install certificates:

# For Python installed via Homebrew
/usr/local/bin/python3 -m pip install --upgrade certifi

# For system Python
sudo /Applications/Python\ 3.10/Install\ Certificates.command

Linux: Permission denied errors

Ensure scripts are executable:

chmod +x $(which skydiscover-run)
chmod +x $(which skydiscover-viewer)

Next Steps

Quick Start

Run your first discovery in under 5 minutes

Configuration

Learn how to configure search algorithms and models

CLI Reference

Complete command-line interface documentation

Python API

Use SkyDiscover programmatically in your Python code