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 and pandas. SciPy, tqdm, and scikit-learn are optional extras.

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[scipy]

Adds scipy for distribution-backed search-space dimensions.

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, scipy, and 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

pandas < 3.0.0

Search data storage and manipulation

Optional Dependencies

Package

Purpose

tqdm >= 4.48 (extra: progress)

Progress bars during optimization

scipy < 2.0.0 (extra: scipy)

Distribution-backed search-space dimensions

scikit-learn >= 0.21, != 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