ConfigSpace

1.2.2 · active · verified Thu Apr 16

ConfigSpace is a Python library designed to manage configuration spaces for automated algorithm configuration and hyperparameter optimization tasks. It provides a straightforward API for defining hyperparameters, their ranges, conditional dependencies, and forbidden clauses. ConfigSpace is frequently used in AutoML tools such as SMAC3, BOHB, and auto-sklearn. The current stable version is 1.2.2, released on December 19, 2025, and it maintains an active release cadence.

Common errors

```
ERROR: Command errored out with exit status 1: command: 'python.exe' 'pip' install ... -- setuptools wheel numpy Cython ... AttributeError: type object 'Callable' has no attribute '_abc_registry'
```
cause This error, particularly the `_abc_registry` AttributeError, often occurred during the installation of older ConfigSpace versions (pre-1.1) due to incompatibilities with specific Python or `pip` environments, especially when `Cython` was a direct build dependency.

fix Ensure you are using Python 3.9+ and the latest `pip`. ConfigSpace 1.1+ removed the direct Cython dependency. If upgrading ConfigSpace is not an option, try `pip install --no-build-isolation ConfigSpace==<version>` or downgrade `numpy` and `Cython` to versions compatible with your Python environment and the ConfigSpace version.
```
ImportError: building ConfigSpace against numpy 1.20.0+ results in problems when importing with older numpy versions.
```
cause ConfigSpace compilation against NumPy 1.20.0 or newer can lead to `ImportError` when the runtime environment uses an older NumPy version, due to changes in NumPy's internal object sizes (`PyObject size`).

fix When installing, ensure ConfigSpace is built against the NumPy version already present in your environment. You can try `pip install --no-build-isolation ConfigSpace` to use the installed NumPy, or specify a NumPy version during build by modifying `pyproject.toml` or using a constrained environment.
```
Errors when reading/writing ConfigurationSpace objects, especially with Forbidden or Condition clauses.
```
cause Older versions of ConfigSpace had issues with serialization and deserialization of complex ConfigurationSpaces containing conditional dependencies or forbidden clauses, particularly to formats like JSON or PCS.

fix Upgrade to the latest ConfigSpace version, as many serialization bugs were fixed in later releases (e.g., around versions 0.5.0, 0.6.0, 1.0.1). Refer to the `Serialization` reference in the documentation for best practices.

Warnings

breaking The 'q' parameter for numerical hyperparameters (e.g., `FloatHyperparameter`, `IntegerHyperparameter`) was removed in ConfigSpace 1.0. This change simplifies the API.
Fix: Instead of `q`, consider using `OrdinalHyperparameter` if discrete steps are strictly required, or rely on the distribution properties directly for numerical parameters. Check the `Hyperparameters` reference in the documentation.
deprecated Many older functions were deprecated in ConfigSpace 1.1 as part of an API simplification and clarity improvement. While efforts were made to maintain backward compatibility, using the new functionality is recommended.
Fix: Consult the official documentation for the updated API. Specifically, newer ways to define hyperparameters directly in `ConfigurationSpace` or via simple functions are preferred over direct type instantiation for common use cases.
gotcha Using `EqualsCondition` or `InCondition` with `Float` hyperparameters can lead to unexpected behavior due to floating-point numerical rounding issues.
Fix: Avoid direct equality or inclusion checks on float values in conditions. Consider using ranges or slightly adjusted bounds for comparisons if necessary, or refactor your conditions to use other hyperparameter types where precision is guaranteed.
breaking ConfigSpace version 1.2.2 (and potentially earlier 1.x releases) dropped official support for Python 3.8. The library now explicitly requires Python 3.9 or higher.
Fix: Upgrade your Python environment to 3.9 or a newer supported version (e.g., 3.10, 3.11, 3.12, 3.13, 3.14).

Install

pip install ConfigSpace PyPI

Imports

ConfigurationSpace

from ConfigSpace import ConfigurationSpace

Float
```
from ConfigSpace import Float
```
Integer
```
from ConfigSpace import Integer
```
Categorical
```
from ConfigSpace import Categorical
```

Quickstart

This quickstart demonstrates how to create a `ConfigurationSpace` object and add `Float` and `Integer` hyperparameters with defined ranges and default values. It then shows how to sample a single configuration from the space and access its values.

from ConfigSpace import ConfigurationSpace, Float, Integer

# Create a simple ConfigurationSpace
cs = ConfigurationSpace(space={
    "alpha": (0.0, 1.0, 0.5), # UniformFloat with lower, upper, default
    "max_iter": (10, 100, 55), # UniformInteger with lower, upper, default
}, seed=1234)

print(cs)

# Sample a configuration
config = cs.sample_configuration()
print(config)

# Access values like a dictionary
print(f"Alpha: {config['alpha']}")

view raw JSON →