Install & Compatibility
Where this runs
tested against v0.16.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
✓ 85.4s
py 3.11
✕ build_error
✓ 80.8s
py 3.12
✕ build_error
✓ 68.5s
py 3.13
✕ build_error
✓ 64.9s
py 3.9
✕ build_error
✕ timeout
5018MB installed
● package 5018MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
SingleTaskGP
✓ from botorch.models import SingleTaskGP
LogExpectedImprovement
✓ from botorch.acquisition import LogExpectedImprovement
✗ from botorch.acquisition import ExpectedImprovement
Use LogExpectedImprovement (qLogEI) for numerical stability and improved optimization performance, as qEI has known numerical issues.
fit_gpytorch_mll
✓ from botorch.fit import fit_gpytorch_mll
ExactMarginalLogLikelihood
✓ from gpytorch.mlls import ExactMarginalLogLikelihood
optimize_acqf
✓ from botorch.optim import optimize_acqf
This quickstart demonstrates a basic Bayesian Optimization loop with BoTorch: initializing training data, fitting a Gaussian Process model, constructing an acquisition function (LogExpectedImprovement for numerical stability), and optimizing it to propose the next best candidate.
import torch
from botorch.models import SingleTaskGP
from botorch.acquisition import LogExpectedImprovement
from botorch.fit import fit_gpytorch_mll
from gpytorch.mlls import ExactMarginalLogLikelihood
from botorch.optim import optimize_acqf
from botorch.models.transforms import Normalize, Standardize
# 1. Define objective function (e.g., a simple 2D function)
def objective_function(x):
return 1 - (x - 0.5).norm(dim=-1, keepdim=True)
# 2. Generate initial training data
train_X = torch.rand(10, 2, dtype=torch.double) * 2
train_Y = objective_function(train_X)
train_Y += 0.1 * torch.randn_like(train_Y) # Add some noise
# 3. Fit a Gaussian Process model
gp = SingleTaskGP(
train_X=train_X,
train_Y=train_Y,
input_transform=Normalize(d=2),
outcome_transform=Standardize(m=1),
)
mll = ExactMarginalLogLikelihood(gp.likelihood, gp)
fit_gpytorch_mll(mll)
# 4. Construct an acquisition function
# Use LogExpectedImprovement for better numerical stability
log_ei = LogExpectedImprovement(model=gp, best_f=train_Y.max())
# 5. Optimize the acquisition function to get the next candidate
bounds = torch.stack([torch.zeros(2), torch.ones(2)]).to(torch.double)
candidate, acq_value = optimize_acqf(
acq_function=log_ei,
bounds=bounds,
q=1,
num_restarts=5,
raw_samples=20,
)
print(f"Next candidate: {candidate}")
print(f"Acquisition function value at candidate: {acq_value}")
# (Optional) Evaluate the new candidate and update the model in a loop
# new_X = candidate
# new_Y = objective_function(new_X)
# train_X = torch.cat([train_X, new_X])
# train_Y = torch.cat([train_Y, new_Y])
# ... refit model ...
Debug
Known issues
breakingBoTorch v0.17.0+ requires Python >=3.11 and PyTorch >=2.2. Ensure your environment meets these minimum versions before upgrading.fixUpgrade Python to 3.11+ and PyTorch to 2.2+. Check the BoTorch `CHANGELOG.md` or official documentation for precise version requirements with each new minor release.
affects: >=0.17.0
breakingBoTorch v0.17.1+ requires GPyTorch >=1.15.2 and `linear_operator >=0.6.1`. Older versions of these dependencies will cause compatibility issues.fixUpdate GPyTorch to >=1.15.2 and `linear_operator` to >=0.6.1.
affects: >=0.17.1
deprecatedThe `qExpectedImprovement` acquisition function has known numerical issues and is strongly recommended to be replaced by `qLogExpectedImprovement` for improved stability and performance.fixReplace `qExpectedImprovement` with `qLogExpectedImprovement` in your code. They share the same API.
affects: >=0.16.1 (warning issued in 0.16.1, affected in 0.17.x)
breakingSeveral APIs were removed in BoTorch v0.17. These include `get_fitted_map_saas_ensemble`, `qMultiObjectiveMaxValueEntropy`, `FullyBayesianPosterior`, the `task_feature` parameter from `SingleTaskGP.construct_inputs`, and the `fixed_features` argument from `optimize_acqf_homotopy`.fixConsult the `CHANGELOG.md` for specific replacements or alternative approaches. Plan for refactoring code that uses these removed components.
affects: >=0.17.0
gotchaBoTorch is a low-level API for Bayesian Optimization research. For general-purpose Bayesian Optimization and experiment management, users not actively doing research on BO are recommended to use Ax, which provides a user-friendly interface on top of BoTorch.fixConsider starting with Ax (Meta's Adaptive Experimentation platform) if you need a simpler, more managed BO workflow. If custom models or acquisition functions are needed, these can be plugged into Ax.
affects: all
breakingThe default hyperparameter priors for most models were updated in v0.12.0 to use dimension-scaled log-normal priors. This significantly improves robustness to dimensionality but might alter results for models fitted with older versions.fixReview existing models for potential changes in optimization behavior. If consistent results with older versions are critical, carefully check model initialization or pin to an earlier BoTorch version.
affects: >=0.12.0
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'botorch.utils.multi_objective'
The specific module or its contents have been moved, renamed, or deprecated in the installed version of BoTorch, or it might be located under a different path due to API evolution.
fixConsult the official BoTorch documentation for your installed version (0.17.2) to find the correct import path for the desired functionality. Often, modules related to specific features might be consolidated or reorganized.
BotorchTensorDimensionError: An explicit output dimension is required for targets. Expected Y with dimension: 1 (got 2).
BoTorch models, particularly those based on GPyTorch, expect target tensors (e.g., `train_Y`) to have an explicit last dimension representing the output dimension, even for single-output tasks. If your tensor is `(n,)`, it needs to be `(n, 1)`.
fixReshape your target tensor `Y` to include an explicit output dimension. For example, use `train_Y = train_Y.unsqueeze(-1)` or `train_Y = train_Y.reshape(-1, 1)` to add a trailing dimension of size 1.
AttributeError: 'SimpleCustomGP' object has no attribute 'num_outputs'
When defining a custom GPyTorch model to be used within BoTorch, the model class needs to explicitly define the `_num_outputs` attribute to indicate the number of outputs it produces.
fixAdd `_num_outputs = 1` (or the appropriate number of outputs for your model) as a class attribute to your custom GPyTorch model definition, for instance: `class SimpleCustomGP(ExactGP, GPyTorchModel): _num_outputs = 1`.
RuntimeError: Expected object of device type cuda but got device type cpu
This common PyTorch error occurs when an operation attempts to interact with tensors or models that are located on different devices (e.g., one on a CUDA-enabled GPU and another on the CPU). BoTorch, being built on PyTorch, frequently encounters this.
fixEnsure that all tensors and models involved in an operation are explicitly moved to the same device (either CPU or GPU). Define a device variable (e.g., `device = torch.device('cuda' if torch.cuda.is_available() else 'cpu')`) and apply `.to(device)` to all relevant tensors and models, for example: `my_tensor.to(device)` and `my_model.to(device)`. Upgrade
Version history
0.18.1latest on PyPI · released Jun 8, 2026
Audit
Dependencies
pythonrequiredRequires Python >=3.11 for BoTorch v0.17.0+.
torchrequiredBoTorch is built on PyTorch. Requires PyTorch >=2.2 for BoTorch v0.17.0+.
gpytorchrequiredProvides state-of-the-art probabilistic models; required GPyTorch >=1.15.2 for BoTorch v0.17.1+.
linear_operatorrequiredRequired for GPyTorch. Requires linear_operator >=0.6.1 for BoTorch v0.17.1+.
pyro-pplrequiredRequired for some advanced probabilistic modeling features (e.g., fully Bayesian models). Requires pyro-ppl >=1.8.4.
scipyrequiredUsed for optimization routines.
multiple-dispatchrequiredA utility dependency.
AxoptionalOften used as a higher-level platform for experiment management and simplified Bayesian Optimization interface, but not a direct dependency of the BoTorch library.