Registry / ai-ml / optax
library0.2.8pypypi✓ verified 23d ago

Optax is a gradient processing and optimization library designed for JAX. It provides a rich set of optimizers (Adam, SGD, etc.), learning rate schedules, and gradient transformations that can be composed to build custom optimization pipelines. It's actively developed by DeepMind/Google, with the current stable version being 0.2.8, and follows a release cadence tied to JAX ecosystem developments, often releasing minor versions for bug fixes and new features.

pip install optax jax jaxlib
INSTALL
IMPORT
SIG · OPTAX
O
optax
ai-mlpythonv0.2.8
Install
20.2s avg
Import
2763ms
Disk
592MB
Pass rate
5/ 10
Env Coverage5 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v0.2.8 · 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
musl
py 3.103.910 runs
build_error
glibc
py 3.103.910 runs
installs and imports cleanly · install 20.2s · import 2.763s · 566MB
592MB installed
● package 592MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

optax
import optax
adam
import optax optimizer = optax.adam(...)
from optax import optimizers.adam
Optimizers like adam are directly under the `optax` namespace, not a nested `optimizers` submodule.
chain
from optax import chain optimizer = chain(...)
import optax.chain
`chain` is a function directly under the `optax` module, not a submodule.

This quickstart demonstrates a basic training loop with Optax and JAX. It defines a simple linear model and a mean squared error loss. An Adam optimizer is initialized, and a `train_step` function is created, leveraging `jax.grad` to compute gradients and Optax to apply updates. The `train_step` is `jax.jit`-compiled for efficiency. The loop iteratively updates parameters and optimizer state to minimize the loss.

import jax import jax.numpy as jnp import optax # 1. Define a simple model and loss function def model(params, x): return params['w'] * x + params['b'] def loss_fn(params, x, y): predictions = model(params, x) return jnp.mean((predictions - y)**2) # 2. Initialize parameters key = jax.random.PRNGKey(0) params = { 'w': jax.random.normal(key, ()), 'b': jax.random.normal(key, ()) } # 3. Choose an optimizer (e.g., Adam) learning_rate = 0.01 optimizer = optax.adam(learning_rate) # 4. Initialize optimizer state opt_state = optimizer.init(params) # 5. Sample data for training x_data = jnp.array([1.0, 2.0, 3.0, 4.0]) y_data = jnp.array([2.0, 4.0, 6.0, 8.0]) # Target: y = 2x # 6. Define a single training step using JAX's jit for performance @jax.jit def train_step(params, opt_state, x, y): # Compute loss and gradients loss_value, grads = jax.value_and_grad(loss_fn)(params, x, y) # Compute updates from gradients and optimizer state updates, new_opt_state = optimizer.update(grads, opt_state, params) # Apply updates to parameters new_params = optax.apply_updates(params, updates) return new_params, new_opt_state, loss_value # 7. Training loop print(f"Initial parameters: {params}") for i in range(100): params, opt_state, loss_value = train_step(params, opt_state, x_data, y_data) if i % 20 == 0: print(f"Step {i}, Loss: {loss_value:.4f}") print(f"Final parameters: {params}") # Expected output for w: ~2.0, b: ~0.0
Debug
Known issues
breakingThe signature of `optimizer.update` changed in Optax 0.1.x to 0.2.x to include `params` as the third argument: `optimizer.update(grads, opt_state, params)`. This is crucial for optimizers that might need current parameter values to compute updates (e.g., for weight decay).
fix
Ensure your `optimizer.update` calls pass the current model parameters as the third argument. If you're coming from an older version, add `params` to your `update` function signature.
affects: <0.2.0
gotchaOptax, like JAX, operates on immutable data structures. When you call `optimizer.update`, it returns a *new* optimizer state and *new* updates. You must reassign these values (`opt_state = new_opt_state`, `params = optax.apply_updates(params, updates)`) otherwise your training loop will not progress.
fix
Always reassign the optimizer state and parameters after calling `optimizer.update` and `optax.apply_updates` respectively, as demonstrated in the quickstart example.
affects: All versions
gotchaOptax expects parameters, gradients, and optimizer states to be JAX PyTrees (e.g., nested dictionaries, lists, tuples, or custom types registered with `jax.tree_util`). Passing non-PyTree structures or incompatible types can lead to errors.
fix
Ensure that your model parameters and the gradients produced by `jax.grad` are consistent PyTree structures. When composing optimizers or transformations, confirm that intermediate results maintain PyTree compatibility.
affects: All versions
Upgrade
Version history
0.2.8latest on PyPI · released Mar 20, 2026
Audit
Dependencies

No dependency data recorded yet.

Agent activity
12 hits · last 30 days
node
10
Resources
optax — pip install optax · libregistry