Skip to main content
Pre-release

This release is a pre-release and may not be stable for production use.

xtrax

PyPI - Version Tests Docs Coverage License: Apache 2.0

A set of composable building blocks for JAX training loops — engine + trainer orchestration, axis tiling strategies, distributed/sharding helpers, streaming output callbacks, and orbax checkpointing — extracted from the author's research code.

Status

xtrax is alpha, experimental software built primarily for the author's personal research use. APIs may change without notice between releases; no backward-compatibility guarantees pre-1.0. Issues and pull requests are welcome, but support is best-effort — the project exists first to serve the author's own JAX training workflows.

Why xtrax?

jax.jit specializes and freezes: it traces your function into a program where every shape is a compile-time constant, and XLA plans all memory for that program up front. The compiler makes the program you gave it fast, but it never restructures it — it cannot narrow a vmap that doesn't fit in memory, cannot batch ragged inputs without a recompile per shape, and cannot notice that most of a batch is duplicates. Those decisions happen in Python, before tracing — and the code that makes them is exactly what gets copy-pasted between research projects.

xtrax packages that pre-trace layer, plus the conveniences that surround it:

  • Axis tiling — declare axes with AxisSpec; BatchPlanner selects Vmap, ChunkedMap (chunked via jax.lax.map), Scan, bucketing, or dedup-gather per axis, and xtrax explain reports why
  • Composable training steps — Trainer with your own loss functions and optimizers
  • Safe arithmetic — safe_norm and safe_reciprocal
  • Distributed helpers — LogicalMesh and sharding utilities over JAX's native machinery

For the full rationale — why this layer has to live above the JIT boundary — see Why xtrax exists.

Installation

pip install xtrax
# For `xtrax run` provenance persistence (zarr metrics stores), also:
pip install "xtrax[io]"

xtrax depends on JAX, optax and orbax, not on Equinox. Equinox models still work: they are plain pytrees to xtrax. Install equinox yourself if you train one.

Requires Python 3.13 or later. The xtrax run CLI persists a provenance store (.xtrax/runs/<run_id>/metrics.zarr) for every invocation by default and fails loud before training if the [io] extra is missing. Add .xtrax/ to your project's .gitignore: run artifacts (manifests, checkpoints, stores) should never dirty your tree — sink git-provenance capture reads git status, and an un-ignored run dir would flip git_dirty=True.

Quick Start

import jax.numpy as jnp
import optax
from xtrax import Trainer, ResumableState, Engine, save_checkpoint, load_checkpoint

# 1. Create a simple loss function
def loss_fn(model, batch):
    predictions = model(batch["inputs"])
    return jnp.mean((predictions - batch["targets"]) ** 2)

# 2. Set up trainer with optimizer
optimizer = optax.adam(1e-3)
trainer = Trainer(loss_fn=loss_fn, optimizer=optimizer)

# 3. Initialize training state
model = ...  # Any pytree of arrays: a dict of arrays, an Equinox module, ...
opt_state = optimizer.init(...)
state = ResumableState(model=model, opt_state=opt_state, step=0)

# 4. Run a training step
new_state, metrics = trainer.step(state, batch={"inputs": x, "targets": y})
print(f"Loss: {metrics['loss']}")

For a complete training loop with callbacks and checkpointing, use the Engine:

from xtrax import Engine, DataModule

# Create or load a DataModule (must implement train_iter())
data = DataModule(...)

# Create an engine with trainer and optional callbacks
engine = Engine(trainer=trainer)

# Run multi-epoch training with checkpoint saving
final_state = engine.fit_sync(
    state=state,
    data=data,
    num_epochs=10,
    checkpoint_dir="./checkpoints"
)

Getting Results Out

Streaming Callbacks

Log metrics asynchronously to files or external services:

from xtrax.engine.io import BoundedCallbackHandler, async_indexed_stream

# Create a custom async callback
class LogCallback:
    async def on_step_end(self, state, metrics):
        print(f"Step {state.step}: {metrics}")

# Use in your Engine
engine = Engine(
    trainer=trainer,
    callbacks=[LogCallback()]
)

Checkpoint Save and Load

Save model state and restore for inference or resumption:

from xtrax import save_checkpoint, load_checkpoint

# After training
save_checkpoint(checkpoint_dir="./checkpoints/final", state=final_state)

# Load for inference
restored_state = load_checkpoint(checkpoint_dir="./checkpoints/final")
model = restored_state.model

# Run inference
predictions = model(test_inputs)

Documentation

Full API docs, architecture guides, and advanced examples at xtrax.readthedocs.io.

License

Licensed under the Apache License 2.0.

Citation

If you use xtrax in research, please cite it:

@software{xtrax,
  title = {xtrax: High-Performance Composable JAX Training},
  author = {Russo, Marielle},
  version = {0.4.0a6},
  year = {2026},
  url = {https://github.com/maraxen/xtrax}
}

Metadata

Release files for xtrax 0.4.1b7

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for xtrax 0.4.1b7
File Size Uploaded Provenance Actions
xtrax-0.4.1b7.tar.gz 3.9 MB With provenance Details for xtrax-0.4.1b7.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for xtrax 0.4.1b7
File Interpreter ABI Platform Actions
xtrax-0.4.1b7-py3-none-any.whl Python 3 none any Details for xtrax-0.4.1b7-py3-none-any.whl

Total release size: 4.7 MB

Release files / xtrax-0.4.1b7.tar.gz

Download URL xtrax-0.4.1b7.tar.gz
Size 3.9 MB
Tags Source
SHA-256 checksum
How to use checksums
2784fc6c23928624fa1067753bcc2b80ffb02fd20d8f796023ae9e7a953f190c
BLAKE2b-256 checksum
How to use checksums
51add9650bb7b1e30f17b7c49ca3cbccf9ee08dda25b22fcbac846eb1b3bc3c3
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 4, 2026.

Transparency log

Release files / xtrax-0.4.1b7-py3-none-any.whl

Download URL xtrax-0.4.1b7-py3-none-any.whl
Size 818.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
392820205f7d677ff18d99e5694b6ea00f3ec748a70d7e9c85eee6da7d8fc046
BLAKE2b-256 checksum
How to use checksums
67016513e7320401bdad3d4d3607d7482d596244e679018848c82c39826e6a50
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 4, 2026.

Transparency log

Security for xtrax 0.4.1b7

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for xtrax-0.4.1b7.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 4, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release
Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page