Install & Compatibility
Where this runs
tested against v4.4.4 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.412s · 91.5MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 3.7s · import 0.434s · 88MB
92MB installed
● package 92MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
fmin2
✓ import cma
cma.fmin2(...)
✗ cma.fmin() (older interface)
`cma.fmin2` is the recommended functional interface for running a complete minimization with additional options like restarts and noise handling. The older `cma.fmin` had a different return signature.
CMAEvolutionStrategy
✓ import cma
es = cma.CMAEvolutionStrategy(...)
es.ask()
es.tell(...)
For an 'ask-and-tell' interface, providing more control over the iteration loop. `cma.fmin2` returns an instance of this class.
This quickstart optimizes the 10-dimensional Rosenbrock function using `cma.fmin2`, starting from an initial solution of all 0.1s and an initial step-size (sigma) of 0.5. It demonstrates how to define an objective function and call the primary optimization interface.
import cma
import numpy as np
def rosenbrock(x):
"""The Rosenbrock function for demonstration."""
return sum(
100.0 * (x[i + 1] - x[i]**2)**2 + (1 - x[i])**2
for i in range(len(x) - 1)
)
# Define initial solution and initial step-size (sigma)
# For a 10-dimensional problem, starting near the origin.
initial_solution = 10 * [0.1] # [0.1, 0.1, ..., 0.1]
initial_sigma = 0.5
# Run the CMA-ES optimization using fmin2
# fmin2 returns (x_best, CMAEvolutionStrategy_instance)
x_best, es = cma.fmin2(
rosenbrock,
initial_solution,
initial_sigma,
options={'maxfevals': 10000, 'verb_log': 0} # Limit evaluations, suppress logging for quick run
)
print(f"Optimization finished after {es.result.evaluations} evaluations.")
print(f"Best solution found: {np.round(x_best, 4)}")
print(f"Objective value at best solution: {es.result.fbest}")
# Detailed results can be accessed via es.result or es.result_pretty()
# print(es.result_pretty())
cma --version
Debug
Known issues
breakingThe return signature of `cma.fmin` changed significantly. Prior to version 2.4.2, `cma.fmin` returned a 10-tuple. Since version 2.4.2, `cma.fmin2` (the recommended interface) returns a `(x_best, es)` tuple, where `es` is a `CMAEvolutionStrategy` instance containing all detailed results in `es.result`. Update old code to use `fmin2` and access results through the `es` object.fixUse `cma.fmin2()` and access results via the returned `CMAEvolutionStrategy` instance (e.g., `es.result.xbest`, `es.result.fbest`).
affects: <= 2.4.1 (fmin) vs >= 2.4.2 (fmin2)
breakingThe `cma.constraints_handling.BoundTransform` class was deprecated/temporarily missing in version 4.1.0. While re-added in 4.4.2 for compatibility, the recommended and stable way to handle bound constraints is `cma.BoundDomainTransform`.fixSwitch to using `cma.BoundDomainTransform` for consistent boundary handling.
affects: 4.1.0 - 4.4.1
gotchaThe library explicitly states that optimization in 1-D is not supported and will raise a `ValueError`. CMA-ES is typically designed for higher-dimensional problems.fixEnsure the optimization problem has a dimensionality greater than one. For 1D optimization, consider other algorithms.
affects: All versions
gotchaOlder versions of `pycma` (prior to 4.4.2) experienced plotting issues when used with `matplotlib > 3.8.0`. These compatibility problems have been addressed in recent releases.fixUpgrade to `cma` version 4.4.2 or later to ensure compatibility with recent `matplotlib` versions.
affects: < 4.4.2
gotchaThe `cma.purecma` submodule, while having minimal dependencies (no `numpy` requirement), is significantly slower than the main `cma` implementation, which heavily relies on `numpy` for performance.fixFor performance-critical applications, always ensure `numpy` is installed and use the main `cma` module (e.g., `cma.fmin2`, `cma.CMAEvolutionStrategy`). `cma.purecma` is better suited for educational purposes or environments where `numpy` cannot be installed.
affects: All versions
Upgrade
Version history
4.4.4latest on PyPI · released Feb 25, 2026
Audit
Dependencies
numpyrequiredRequired for the main `cma.CMAEvolutionStrategy` implementation for array processing. The `cma.purecma` submodule can function without it but is slower.
matplotliboptionalHighly recommended for plotting optimization progress and results.