Install & Compatibility
Where this runs
tested against v1.3.1 · 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
py 3.10
✕ build_error
✕ timeout
py 3.11
✕ build_error
✕ timeout
py 3.12
✕ build_error
1/12 runs
py 3.13
✕ build_error
9/12 runs
py 3.9
✕ build_error
✕ timeout
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Client
✓ from ax import Client
The consolidated import for the primary entry point, also `from ax.api.client import Client` is correct for the new public API.
AxClient
✓ from ax.api.client import Client
✗ from ax.service.ax_client import AxClient
The `AxClient` from `ax.service.ax_client` is part of the deprecated 'Service API'; users are encouraged to use the `ax.api` entry point, which provides the `Client` class.
RangeParameterConfig
✓ from ax import RangeParameterConfig
Commonly imported alongside Client for defining search spaces.
This quickstart initializes an Ax client, configures an experiment to minimize the Booth function, runs 20 trials, and then retrieves the best-found parameters. It demonstrates the core loop of defining a search space, getting new trials, evaluating them, and logging results back to Ax.
from ax import Client, RangeParameterConfig
def booth_function(x1, x2):
return (x1 + 2 * x2 - 7)**2 + (2 * x1 + x2 - 5)**2
client = Client()
client.configure_experiment(
name="booth_function_experiment",
parameters=[
RangeParameterConfig(name="x1", bounds=(-10.0, 10.0), parameter_type="float"),
RangeParameterConfig(name="x2", bounds=(-10.0, 10.0), parameter_type="float"),
],
objectives={
"booth": RangeParameterConfig(name="booth", bounds=(-100.0, 100.0), parameter_type="float", minimize=True)
}
)
for _ in range(20):
for trial_index, parameters in client.get_next_trials(max_trials=1).items():
result = booth_function(parameters["x1"], parameters["x2"])
client.complete_trial(
trial_index=trial_index,
raw_data={"booth": (result, 0.0)} # Tuple (mean, SEM)
)
best_parameters, metrics = client.get_best_parameterization()
print("Best parameters found:", best_parameters)
print("Corresponding metrics:", metrics)
Debug
Known issues
breakingAx 1.2.3 and later requires Python 3.11+. Older Python versions will cause installation or runtime failures.fixUpgrade your Python environment to 3.11 or newer. `conda create -n myenv python=3.11; conda activate myenv` or use `pyenv`.
affects: >=1.2.3
breakingAx 1.2.3 and later requires Pandas 3.0+ and BoTorch 0.17.0+ due to breaking changes in their APIs. Older versions may lead to `AttributeError` or unexpected behavior.fixEnsure `pandas` and `botorch` are updated: `pip install --upgrade pandas botorch`.
affects: >=1.2.3
breakingThe `transition_to` argument is now explicitly required on `TransitionCriterion` classes in Ax 1.2.3+. Code relying on implicit transitions will fail.fixWhen defining a `GenerationStrategy` with `TransitionCriterion`, explicitly specify `transition_to` for each criterion.
affects: >=1.2.3
deprecatedThe `AxClient` and the 'optimize' loop API (e.g., `ax.service.managed_loop.optimize`) are deprecated as of Ax 1.2.2. While still functional, they may be removed or changed incompatibly in future major/minor releases.fixMigrate to the new public API through `from ax.api.client import Client` and manage the optimization loop manually.
affects: >=1.2.2
gotchaSQLAlchemy is not a direct dependency in current Ax versions but is recommended for SQL storage. If installed, `SQLAlchemy>=2.0` can cause compatibility issues with Ax's internal storage components.fixIf using SQL storage, ensure `SQLAlchemy` is installed but keep its version below 2.0 (e.g., `pip install 'SQLAlchemy<2.0'`) until Ax explicitly supports 2.0. Ax 1.2.2 notes that SQLAlchemy will become a required dependency in a future release.
affects: <2.0 (Ax's internal compatibility)
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'ax-platform'
The `ax-platform` package is not installed or not available in the current Python environment.
fixInstall the package using pip: `pip install ax-platform`. Ensure your virtual environment is activated.
ERROR: Could not find a version that satisfies the requirement ax-platform
This usually indicates an incompatible Python version. Ax 1.2.3+ requires Python 3.11 or newer.
fixUpgrade your Python version to 3.11+ or ensure your environment satisfies the `requires_python` metadata. You might also need to upgrade pip: `python -m pip install --upgrade pip`.
AttributeError: 'RangeParameter' object has no attribute 'lower' (or similar attribute errors related to Pandas/BoTorch)
Version mismatch with core dependencies like Pandas or BoTorch. Ax 1.2.3+ expects specific versions (Pandas 3.0+, BoTorch 0.17.0+).
fixUpdate Pandas and BoTorch: `pip install --upgrade pandas botorch`.
OptimizationWarning: Failed to initialize using continuous relaxation. Using `sample_feasible_points` for initialization.
This warning from BoTorch (used by Ax) often indicates numerical issues or a challenging optimization landscape where the initial continuous optimization fails, and a fallback is used. It's often a warning, not a fatal error, but can indicate suboptimal performance.
fixWhile often ignorable, check your search space definition for extreme bounds or constraints. Consider normalizing parameters. If performance is an issue, consult BoTorch documentation or Ax tutorials on advanced model configuration.
SyntaxWarning: invalid escape sequence 'g' (or similar 'SyntaxWarning' related to escape sequences)
This Python warning is often triggered by raw strings (`r'...'`) or unescaped backslashes in older code that might not be fully compliant with newer Python versions' string literal rules (e.g., Python 3.12+). It can appear in internal library code or examples.
fixThis is typically a warning from internal dependencies and might not directly impact your code's functionality, but it can be noisy. Ensure your Python version is compatible with the Ax version. If it's in your code, use raw strings (`r""`) or correctly escape backslashes (`\`).
Upgrade
Version history
1.3.1latest on PyPI · released Jun 9, 2026
Audit
Dependencies
pythonrequiredAx requires Python 3.11 or newer.
pandasrequiredRequired for data handling; Ax 1.2.3+ requires Pandas 3.0+.
botorchrequiredAx's Bayesian optimization is powered by BoTorch. Ax 1.2.3+ requires BoTorch 0.17.0+.
pytorchrequiredIndirect dependency via BoTorch, often manually installed for performance.
sqlalchemyoptionalOptional for SQL storage; will become a required dependency in future versions.
gpytorchoptionalIndirect dependency via BoTorch, sometimes needed for bleeding edge installations.