Install TauOpt#

TauOpt needs Python 3.10 or newer and runs on CPU only: no CUDA, and the engine never allocates a GPU.

Closed beta: nothing to install. The package is not distributed during the closed beta (the PyPI and npm names hold placeholders and the repository is private), and beta participants do not need it: you sign in at app.tauopt.com, mint a tau_ token there, and with it the hosted service at api.tauopt.com (and its MCP server at mcp.tauopt.com, if you drive it from an agent) runs the examples over plain HTTP from Python’s standard library (the hosted examples; Hosted beta: getting started walks the sign-in, the mint and the first loop) or from an agent through the MCP server. The package, with its in-process driver and the local examples, arrives at the public release. The rest of this page is for maintainers and collaborators with repository access, who install from a clone:

git clone https://github.com/talariasci/tauopt && cd tauopt

Access to the repository is by invitation; request it at tauopt.com.

Pick the section for your environment, then run Verify the install and, if you installed the Gaussian-process (GP) strategies, Confirm the GP strategies run. The pip path, the two verification sections, and the air-gapped wheel build were run while validating this page; the uv and conda commands and the air-gapped recipe’s download and target-side install are read from CONTRIBUTING.md, python/pyproject.toml, and pip’s documentation, and were not run.

Choose an extras tier#

The base package is featherweight by design, and import tauopt never imports the math stack, so the default install co-exists with any environment that satisfies httpx>=0.27 and pydantic>=2.7, dependency-constrained HPC venvs included. Math lives behind extras, declared in python/pyproject.toml:

Install target (from the clone)	Adds	What it enables
`"./python"`	`httpx>=0.27`, `pydantic>=2.7`	The hosted client only: `Client(base_url=..., token=...)`
`"./python[local]"`	`numpy>=1.26`, `scipy>=1.11`	The in-process driver, `Client(driver="local")`, with the space-filling strategies `random` and `sobol` (model-free: they spread points over the box, `sobol` evenly)
`"./python[botorch]"`	`torch>=2.4`, `botorch>=0.12`, `gpytorch>=1.13`	The GP strategies `gp_ei`, `ucb_cl`, and `gp_nehvi`
`"./python[all]"`	`[local]` + `[botorch]`	Everything; the tier the quickstart and the example scripts assume

Error messages name the extras by package name (tauopt[local], tauopt[all]); from a clone the matching targets are "./python[local]" and "./python[all]".

Install with pip#

On Linux, for the [botorch] or [all] tier, install CPU torch before the package (the featherweight and [local] tiers pull no torch, so they skip this step). Plain pip resolves the multi-gigabyte CUDA build of torch from PyPI; the CPU index pin in python/pyproject.toml is honored by uv only:
```
pip install torch --index-url https://download.pytorch.org/whl/cpu
```
The checkpoint is the +cpu suffix in pip’s Successfully installed ... torch-<version>+cpu line. An environment that already holds a CUDA torch prints Requirement already satisfied instead and keeps it; start from a fresh virtualenv.
Install the tier you chose:
```
pip install "./python[all]"
```

Install with uv#

uv honors the CPU torch pin in python/pyproject.toml (the [[tool.uv.index]] and [tool.uv.sources] blocks), so no manual torch step is needed inside this repository.

Create the development environment with every extra, from the clone (the repository’s lock resolves for Python 3.12 and newer only; the committed .python-version makes uv pick or download 3.12 on a box whose default Python is older, and --python 3.12 is only an override; the package itself keeps its 3.10 floor, and a built wheel installs there outside this repository):
```
cd python && uv sync --all-extras
```
Run anything inside that environment with uv run, for example one of the example scripts:
```
uv run python examples/branin_local.py
```

The pin applies to this repository’s workspace only. A uv project of your own that depends on TauOpt declares the index itself; copy these two blocks from python/pyproject.toml into that project’s pyproject.toml before adding the dependency, or uv resolves the CUDA build of torch on Linux the same way pip does:

[[tool.uv.index]]
name = "pytorch-cpu"
url = "https://download.pytorch.org/whl/cpu"
explicit = true

[tool.uv.sources]
torch = { index = "pytorch-cpu" }

Install inside a conda or mamba environment#

No conda package exists; pip inside the environment is the path. The conda commands here follow conda’s documented interface.

Create and activate an environment with a supported Python (mamba takes the same arguments):
```
conda create -n tauopt python=3.12 -y
conda activate tauopt
```
Follow Install with pip inside the environment, CPU-torch step included on Linux.

Install on an air-gapped host#

Standard pip wheelhouse mechanics apply. Build the wheelhouse on a connected host with the same operating system, CPU architecture, and Python minor version as the target. The wheelhouse carries TauOpt’s own wheel, so the target host needs the wheelhouse only, never the clone.

On the connected host, from the clone, build TauOpt’s wheel and download every dependency wheel into one directory. The two index options are the Linux CPU-torch pin from Install with pip. pip gives neither index priority over the other; the wheelhouse ends up with CPU torch because the CPU index serves <version>+cpu builds, which rank above the plain <version> on PyPI at the same release, and the CPU index tracks PyPI’s torch releases (a release the CPU index lacked would come from PyPI as the CUDA build). Pin the +cpu build explicitly, which only the CPU index can satisfy; pip index versions torch --index-url https://download.pytorch.org/whl/cpu lists the available ones:
```
pip wheel "./python[all]" "torch==<version>+cpu" -w wheels/ --index-url https://download.pytorch.org/whl/cpu --extra-index-url https://pypi.org/simple
```
<version> is the torch release you want; pip index versions torch --index-url https://download.pytorch.org/whl/cpu lists the ones the CPU index serves.

wheels/ ends up holding tauopt-0.4.0-py3-none-any.whl next to the dependency wheels. pip download is no substitute here: it resolves a local-directory requirement without saving the directory’s own wheel, so a wheelhouse built with it lacks TauOpt itself.
Copy wheels/ to the target host.
On the target host, install by distribution name from the wheelhouse and nothing else:
```
pip install --no-index --find-links wheels/ "tauopt[all]"
```

Verify the install#

Print the version:

python -c "import tauopt; print(tauopt.__version__)"

0.4.0

Nothing in the math stack has been imported at this point. Asking for the local driver without the math extras fails loudly instead of degrading:

ImportError: the local driver needs the math extras: pip install 'tauopt[local]' (or 'tauopt[all]' to include the GP strategies via 'tauopt[botorch]')

Confirm the GP strategies run#

A missing [botorch] extra never raises: the never-fail ladder skips the unavailable GP rungs and answers from the space-filling strategies, recording the skipped rung in each suggestion’s provenance. Two checks make the tier visible.

List the strategies this environment can serve:

python -c "from tauopt.engine.strategies import registry; print(sorted(registry.available()))"

['gp_ei', 'gp_nehvi', 'random', 'sobol', 'ucb_cl']

Without [botorch] the list is ['random', 'sobol']: gp_ei, ucb_cl, and gp_nehvi each require that extra.

Run a short loop and print each suggestion’s strategy and fallback_from:

import math

from tauopt import Client

client = Client(driver="local")
exp = client.create_experiment(
    name="gp-tier-check",
    parameters=[
        {"name": "x1", "type": "double", "bounds": (-5.0, 10.0)},
        {"name": "x2", "type": "double", "bounds": (0.0, 15.0)},
    ],
    metric={"name": "branin", "objective": "minimize"},
    observation_budget=8,
)
for _ in range(8):
    sug = client.suggest(exp.id)
    x1, x2 = sug.assignments["x1"], sug.assignments["x2"]
    value = (x2 - 0.129 * x1**2 + 1.592 * x1 - 6) ** 2 + 9.602 * math.cos(x1) + 10
    client.observe(exp.id, suggestion_id=sug.id, value=value)
    print(sug.provenance.strategy, sug.provenance.fallback_from)

sobol None
sobol None
sobol None
sobol None
gp_ei None
gp_ei None
gp_ei None
gp_ei None

The first four asks are the policy’s space-filling bootstrap; from the fifth on, gp_ei answers and fallback_from stays None. If every line past the bootstrap reads sobol or random, the GP strategies are not running (fallback_from: gp_ei with strategy: ucb_cl still ran a GP). The two usual causes are a missing [botorch] extra and, under load, asks that exceed the default 10-second timebox_s and degrade down the ladder; both are covered in Troubleshooting.