# SMAC3 pairs Bayesian optimization with racing, and dropped pyrfr in 2.4

> SMAC3 finds good hyperparameter configurations by combining a surrogate model with an aggressive racing mechanism that decides which of two configurations is better, and since v2.4.0 the default surrogate comes from scikit-learn instead of a C++ random forest. That change removed the compiler toolchain from the default install and pushed the old model behind a legacy facade.

**automl/SMAC3** — SMAC3: A Versatile Bayesian Optimization Package for Hyperparameter Optimization

- Repository: https://github.com/automl/SMAC3
- Website: https://automl.github.io/SMAC3/latest/
- Stars: 1,261 · Forks: 248
- Language: Python
- License: NOASSERTION
- Published: 2026-10-17 · Updated: 2026-10-17 · Language: en
- Canonical page: https://hysenlabs.com/projects/automl-smac3

## What the racing mechanism adds

The README describes SMAC as a framework for Bayesian optimization whose main core consists of Bayesian optimization combined with an aggressive racing mechanism to efficiently decide which of two configurations performs better.

That second half is what distinguishes it. Plain Bayesian optimization fits a surrogate over evaluated configurations and suggests the next candidate. Racing is what makes that affordable: when two configurations are close, SMAC spends budget on running them under progressively harsher conditions and kills the loser early, so expensive full evaluations are spent only on configurations that survive.

For the kind of work SMAC targets, an algorithm configuration search over a machine learning pipeline on a dataset, that is the difference between a search that finishes and one that does not.

The scope is broader than tuning alone. The topic tags include algorithm configuration, so SMAC is used to configure optimizers themselves, not only model hyperparameters. The visual companion for that purpose is DeepCAVE, a separate AutomL project described as a visualization and analysis tool for AutoML runs and especially for the hyperparameter optimization sub-problem.

SMAC3 is developed by the AutoML groups of the universities of Hannover and Freiburg, and is a featured optimizer on AutoML Space.

## The surrogate model changed in 2.4.0

The most consequential recent change is not in the algorithm but in the dependency.

Starting from 2.4.0, SMAC uses the random forest from scikit-learn as the default surrogate model for HPO tasks, instead of the random forest from pyrfr. The README is explicit about the consequence for users: no more C++ toolchain for the default path.

The old model is still reachable. Calling `smac.facade.old.HyperparameterOptimizationRFRFacade` or `smac.facade.old.MultiFidelityRFRFacade` selects the pyrfr surrogate, and getting it working requires build tools first, gcc, gxx and swig, after which you install the extra:

```bash
conda install gxx_linux-64 gcc_linux-64 swig
```

```bash
pip install smac[pyrfr]
```

The `pyrfr` extra is declared in setup.py as `pyrfr>=0.9.0`.

So this is a library that used to require a compiler and no longer does, with the compiled path preserved behind a legacy namespace. If you have benchmarks or a paper that depend on the pyrfr surrogate, note that reproducing them now takes extra work; if you are starting fresh, the sklearn path is the one to use.

The README also says SMAC3 is written in Python 3 and continuously tested with Python 3.8, 3.9 and 3.10, and works with newer versions, with its random forest written in C++.

## Installing and running the minimal example

The installation instructions are for Linux, with Windows and Mac pointed at the documentation. The demonstrated path uses conda to create a Python 3.10 environment:

```bash
conda create -n SMAC python=3.10
conda activate SMAC
```

Then the package itself:

```bash
pip install smac
```

Contributors use a different path, `git clone` plus `make install-dev`, which installs the dev extras and wires up pre-commit.

The minimal example is short enough to read in full, and it shows the shape of the API rather than a specific problem:

```py
from smac import HyperparameterOptimizationFacade, Scenario

scenario = Scenario(configspace, deterministic=True, n_trials=200)
smac = HyperparameterOptimizationFacade(scenario, train)
incumbent = smac.optimize()
```

Three things to note. The search space comes from ConfigSpace, a separate package SMAC depends on with a minimum version, and the README's example builds a `ConfigurationSpace({"C": (0.100, 1000.0)})` around the SVM C parameter. The budget is declared in the `Scenario` object as `n_trials`, alongside a `deterministic` flag for whether the target function is noisy. And the facade name carries the configuration: `HyperparameterOptimizationFacade` rather than something generic, because v2.0 restructured the package around facades.

The example targets are returned by your function and SMAC minimises or maximises accordingly, here returning `1 - np.mean(scores)`.

## What v2.0 removed, and why it matters now

The README keeps a section on changes in v2.0 that is worth reading before you plan a migration in either direction.

All facades and intensifiers support multi-objective, multi-fidelity and multi-threading natively now, along with an ask-and-tell interface and the ability to continue a run wherever you left off.

Then the removals. pSMAC is gone, because when you specify the number of workers SMAC automatically uses multi-threading for evaluating trials. The command-line interface was removed during the cleanup, though calling a target function from a script is still supported. Runtime optimization was removed. And Python 3.7 is no longer supported. The README's instruction for anyone depending on those is to keep using v1.4.

The pSMAC removal is the one that changes how you parallelise. Under the old scheme, parallelisation was a separate concept with its own entry point. Under v2, it is a property of the optimization run itself.

The examples directory mirrors that structure with numbered folders: `1_basics`, `2_multi_fidelity`, `3_multi_objective`, `4_advanced_optimizer` and `5_commandline`. The presence of a command line example alongside a README statement that the CLI was removed is worth resolving against the current documentation, since the examples directory is a reasonable place for either to be out of date.

## Versions, licensing and where the maintenance signals are

The recent releases are v2.4.1 on 2026-09-10, v2.4.0 on 2026-04-10 and a tag written `v.2.3.1` from 2025-01-23, with the stray dot in that tag name being a small indicator that release hygiene is not perfectly mechanical here. The last push was on 2026-10-14 and the repository is not archived.

The Makefile carries `VERSION := 2.3.1` while the released package is 2.4.1, so the Makefile version constant is stale relative to the package. The Makefile itself is a conventional development entry point with targets for install-dev, check, format, build, tests, docs, examples, clean and publish, and a comment at the top explaining that the targets are configured to run only short tasks, with the longer ones handled in GitHub Actions.

There is a `benchmark/` directory at the root, which for an optimizer package is the interesting one, since the whole value proposition rests on how efficiently it spends a budget. The repository also carries a CHANGELOG.md, a CITATION.cff, a Makefile, a `.binder/` directory for reproducible notebook environments and mkdocs configuration for the documentation site.

On licensing, the README states the 3-clause BSD license and points at the LICENSE file. GitHub's metadata does not classify it as standard, so the file is the authoritative text.

The academic citation is the JMLR paper from 2022, volume 23, number 54, with a long author list, and the README asks research users to cite it. The copyright line names the Leibniz University Hannover Institute of AI for 2025.

## Conclusion

Adopt SMAC3 if you are tuning expensive machine learning configurations and want multi-fidelity or multi-objective support that is native rather than bolted on. Verify first which surrogate you are getting, because the default changed to sklearn at v2.4.0 and pyrfr now lives behind `smac.facade.old` and needs a compiler, and note that the Makefile still carries VERSION 2.3.1 while the released package is 2.4.1.

## FAQ

### How do I install SMAC3?

On Linux, create a conda environment with Python 3.10 using `conda create -n SMAC python=3.10` and `conda activate SMAC`, then run `pip install smac`. Contributors use `make install-dev` after cloning. Windows and macOS instructions are in the documentation.

### What changed about the random forest surrogate in SMAC 2.4.0?

SMAC now uses scikit-learn's random forest as the default surrogate instead of pyrfr, which removes the need for a C++ toolchain by default. The pyrfr surrogate remains available through `smac.facade.old.HyperparameterOptimizationRFRFacade` and requires gcc, gxx, swig plus `pip install smac[pyrfr]`.

### What does the racing mechanism in SMAC do?

The README describes it as an aggressive mechanism to efficiently decide which of two configurations performs better, combined with Bayesian optimization. It lets promising configurations be compared under harsher conditions before full evaluation is spent on them.

### How do I set a budget for a SMAC optimization run?

In the Scenario object, with n_trials, alongside a deterministic flag indicating whether the target function is noisy. The minimal example uses `Scenario(configspace, deterministic=True, n_trials=200)` and then calls `HyperparameterOptimizationFacade(scenario, train)` followed by `optimize()`.

## Sources

- [automl/SMAC3 on GitHub](https://github.com/automl/SMAC3)
- [Issues](https://github.com/automl/SMAC3/issues)
- [Project website](https://automl.github.io/SMAC3/latest/)
- [README](https://github.com/automl/SMAC3/blob/main/README.md)
- [Releases](https://github.com/automl/SMAC3/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/automl-smac3