Install & Compatibility
Where this runs
tested against v1.0.12 · 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.920 runs
build_error
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 14.5s · import 5.005s · 348MB
365MB installed
● package 365MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
ng
✓ import nevergrad as ng
Standard alias for the library.
NGOpt
✓ from nevergrad.optimization import NGOpt
✗ from nevergrad.optimizers import NGOpt
Optimizers are located under `nevergrad.optimization` as of recent versions, not a top-level `optimizers` module. `ng.optimizers.NGOpt` is also valid for registry access.
Instrumentation
✓ from nevergrad import parametrization as p
parametrization = p.Instrumentation(...)
✗ from nevergrad.instrumentation import Instrumentation
The `parametrization` module is typically aliased as `p` for convenience and is the recommended way to access parameter types like `Scalar`, `Log`, `Choice`, `Array`.
This quickstart demonstrates how to define a function with mixed continuous, discrete, and categorical parameters using `nevergrad.parametrization.Instrumentation` and then optimize it using `nevergrad.optimizers.NGOpt`. The `minimize` method returns the best parameter set found within the specified budget.
import nevergrad as ng
import numpy as np
def objective_function(learning_rate: float, batch_size: int, architecture: str) -> float:
# Simulate a training process; optimal for lr=0.2, bs=4, arch='conv'
return (learning_rate - 0.2)**2 + (batch_size - 4)**2 + (0 if architecture == 'conv' else 10)
# Define the parameter space using Instrumentation
parametrization = ng.p.Instrumentation(
# Log-distributed scalar for learning_rate
learning_rate=ng.p.Log(lower=0.001, upper=1.0),
# Integer scalar for batch_size
batch_size=ng.p.Scalar(lower=1, upper=12).set_integer_casting(),
# Categorical choice for architecture
architecture=ng.p.Choice(["conv", "fc"]),
)
# Choose an optimizer (NGOpt is a recommended adaptive optimizer)
optimizer = ng.optimizers.NGOpt(parametrization=parametrization, budget=100)
# Minimize the objective function
recommendation = optimizer.minimize(objective_function)
print(f"Optimal hyperparameters: {recommendation.kwargs}")
print(f"Best objective value: {objective_function(**recommendation.kwargs)}")
Debug
Known issues
breakingNevergrad has experienced compatibility issues with NumPy 2.0 due to expired deprecations in NumPy's API, particularly affecting optimizers like `NGOpt` and `NgDS`. While fixes have been merged into the `main` branch, older versions or complex dependency trees might still encounter these problems.fixEnsure `nevergrad` is updated to the latest version (1.0.12 or newer) and consider pinning `numpy<2.0` if compatibility issues persist with other libraries in your environment.
affects: <=1.0.11 (and possibly some 1.0.x if indirect dependencies are not updated)
gotchaThe `parametrization` API (e.g., `ng.p.Instrumentation`, `ng.p.Scalar`, `ng.p.Choice`) is explicitly stated as a 'work in progress' and subject to future breaking changes.fixRefer to the official documentation and GitHub for the most current usage patterns, especially when defining complex parameter spaces.
affects: All 1.x versions
deprecatedThe `colorama` dependency was removed in version 1.0.12. If your application indirectly relied on `nevergrad` for `colorama`'s functionality (e.g., colored terminal output), it will cease to work.fixExplicitly add `colorama` to your project's dependencies if you require its functionality. `pip install colorama`.
affects: >=1.0.12
gotchaSome optimizers, particularly Differential Evolution (DE) algorithms, can be inefficient or perform poorly when provided with very small budgets (e.g., `budget < 60`).fixFor DE algorithms, ensure a sufficient budget. Generally, choose optimizers appropriate for your problem's complexity and available computational budget. Consult the documentation for optimizer-specific recommendations.
affects: All versions
gotchaNot all optimizers support the fully asynchronous 'ask and tell' interface. Optimizers with `no_parallelization=True` will not work correctly in parallel execution environments designed for asynchronous `ask`/`tell` calls.fixCheck the optimizer's documentation or `no_parallelization` attribute if planning parallel evaluations. For such optimizers, consider synchronous execution or an optimizer that explicitly supports asynchronous operations.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'nevergrad'
The Nevergrad library is not installed in your current Python environment.
ValueError: The provided budget (1) is smaller than the minimum number of evaluations required (2)
Some Nevergrad optimizers require a minimum number of evaluations (budget) to start, and the provided budget is insufficient.
fixIncrease the `budget` parameter when initializing the optimizer to at least the minimum required by the specific algorithm, for example:
```python
import nevergrad as ng
optimizer = ng.optimizers.OnePlusOne(parametrization=2, budget=10) # budget increased
```
AttributeError: 'list' object has no attribute 'x'
You are attempting to access an attribute (like `x`, `y`, or `value`) directly from the list of recommendations returned by `optimizer.minimize()` or `optimizer.ask()`, instead of from an individual recommendation object within the list.
fixAccess attributes from the individual recommendation object, which is usually the result of `optimizer.minimize()` or an element from the list returned by `optimizer.ask()`:
```python
import nevergrad as ng
def my_function(x): return x**2
optimizer = ng.optimizers.OnePlusOne(parametrization=1, budget=10)
recommendation = optimizer.minimize(my_function) # recommendation is an object, not a list
print(recommendation.x) # Access 'x' directly from the recommendation object
# If you used optimizer.ask(), it returns a list of recommendations:
# recommendations = optimizer.ask(2)
# for rec in recommendations: print(rec.x)
```
TypeError: 'dict' object is not callable
This error often occurs when you mistakenly try to execute a dictionary as if it were a function, commonly when passing arguments or a parametrization object where a callable is expected by Nevergrad.
fixEnsure that the `optimizer.minimize` method is called with a callable function as its first argument, and that the parametrization is correctly defined and passed separately:
```python
import nevergrad as ng
def my_function(param1, param2):
return param1**2 + param2
# Correct way: pass the function itself, and define parametrization separately
parametrization = ng.p.Instrumentation(param1=ng.p.Scalar(), param2=ng.p.Scalar())
optimizer = ng.optimizers.OnePlusOne(parametrization=parametrization, budget=10)
recommendation = optimizer.minimize(my_function) # my_function is the callable
``` Upgrade
Version history
1.0.12latest on PyPI · released Apr 23, 2025
Audit
Dependencies
numpyrequiredFundamental package for numerical operations.
pandasrequiredUsed for data structures and analysis.
typing-extensionsrequiredRequired for advanced type hinting.