Installation

Gradient-Free-Optimizers can be installed via pip and supports Python 3.10+.

Installing Gradient-Free-Optimizers

Basic Installation

Install GFO from PyPI using pip:

pip install gradient-free-optimizers

This installs GFO with its core dependencies (NumPy, SciPy, and pandas), which is sufficient for all core optimization algorithms.

Installation with Extras

For additional functionality, you can install optional extras:

pip install gradient-free-optimizers[progress]

Adds tqdm for progress bars during optimization.

pip install gradient-free-optimizers[sklearn]

Adds scikit-learn for surrogate models used in Bayesian Optimization, TPE, and Forest Optimizer.

pip install gradient-free-optimizers[full]

Installs all optional dependencies (tqdm + scikit-learn).

Development Installation

To install GFO for development (from source):

# Clone the repository
git clone https://github.com/SimonBlanke/Gradient-Free-Optimizers.git
cd Gradient-Free-Optimizers

# Install in development mode with test dependencies
pip install -e ".[test]"

# Or install with all development dependencies
pip install -e ".[test,docs]"

# Run tests to verify installation
pytest tests/

Dependencies

Core Dependencies

Gradient-Free-Optimizers requires the following packages (automatically installed):

Package

Purpose

numpy >= 1.18.1, < 3.0.0

Numerical operations, array handling, and search space definition

scipy < 2.0.0

Scientific computing and statistical functions

pandas < 3.0.0

Search data storage and manipulation

Optional Dependencies

Package

Purpose

tqdm >= 4.48 (extra: progress)

Progress bars during optimization

scikit-learn >= 0.23 (extra: sklearn)

Surrogate models for SMBO algorithms (Bayesian, TPE, Forest)

Verifying Installation

After installation, verify that GFO works correctly:

import gradient_free_optimizers
import numpy as np

# Check version
print(f"GFO version: {gradient_free_optimizers.__version__}")

# Run a quick optimization
from gradient_free_optimizers import HillClimbingOptimizer

def sphere(params):
    return -(params["x"]**2 + params["y"]**2)

search_space = {
    "x": np.linspace(-5, 5, 50),
    "y": np.linspace(-5, 5, 50),
}

opt = HillClimbingOptimizer(search_space)
opt.search(sphere, n_iter=100)

print(f"Best score: {opt.best_score}")
print(f"Best params: {opt.best_para}")

Expected output:

GFO version: X.X.X
Best score: -0.04  (approximately)
Best params: {'x': 0.2, 'y': 0.0}  (approximately)

Troubleshooting Installation

Python Version Issues

GFO requires Python 3.10 or newer. Check your Python version:

python --version

If you have multiple Python versions, use:

python3.10 -m pip install gradient-free-optimizers

NumPy Compatibility

GFO supports both NumPy 1.x and 2.x. If you encounter issues:

# Install with specific NumPy version
pip install "numpy<2.0" gradient-free-optimizers  # For NumPy 1.x
pip install "numpy>=2.0" gradient-free-optimizers  # For NumPy 2.x

Dependency Conflicts

If you encounter dependency conflicts:

# Create a fresh virtual environment
python -m venv gfo_env
source gfo_env/bin/activate  # On Windows: gfo_env\Scripts\activate
pip install gradient-free-optimizers

Permission Errors

If you get permission errors during installation:

# Install for current user only (recommended)
pip install --user gradient-free-optimizers

# Or use a virtual environment (better practice)
python -m venv myenv
source myenv/bin/activate
pip install gradient-free-optimizers

Missing SMBO Dependencies

If you try to use Bayesian Optimization or other SMBO algorithms without scikit-learn installed, you’ll see an import error. Install with:

pip install gradient-free-optimizers[sklearn]

Installation in Special Environments

Jupyter Notebooks

Install directly in a notebook cell:

!pip install gradient-free-optimizers

Or with extras:

!pip install gradient-free-optimizers[full]

Google Colab

GFO works out of the box in Google Colab:

!pip install gradient-free-optimizers
import gradient_free_optimizers

Docker

Add to your Dockerfile:

FROM python:3.11-slim
RUN pip install gradient-free-optimizers[full]

Conda Environments

While GFO is not on conda-forge yet, you can install via pip in a conda environment:

conda create -n gfo python=3.11
conda activate gfo
pip install gradient-free-optimizers

Using Older Versions

If you need to use an older version of GFO, you can install a specific version:

pip install gradient-free-optimizers==1.5.0

Documentation for older versions is available at: Legacy Documentation (v1.x)

Next Steps