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)

Persistent Compilation Cache

Call xtrax.jax_cache.configure() once at process entry, before the first jax.jit, so every process of a campaign reuses executables an earlier one compiled. xtrax run and xtrax campaign run (every executor, including each Slurm array task) do this for you and take --compilation-cache PATH|off.

Where the cache lives is a fact about the machine; whether a project uses it is a fact about the project. They are configured separately:

  • Directory (first match wins): the path argument, $XTRAX_JAX_CACHE_DIR, $JAX_COMPILATION_CACHE_DIR, then ${XDG_CONFIG_HOME:-~/.config}/xtrax/config.toml. none, off or empty in any of them disables. xtrax carries no default path, and a directory in pyproject.toml is refused: a committed file is pushed to other machines.
  • On/off (first match wins): $XTRAX_JAX_CACHE, then jax_compilation_cache under [tool.xtrax] in the nearest pyproject.toml, then the user config, else on. A project's off holds even when a cluster profile injects $JAX_COMPILATION_CACHE_DIR.
# once per machine: ~/.config/xtrax/config.toml (laptop, workstation, cluster login node)
jax_compilation_cache_dir = "/path/to/flash/jax_cache"
# the consuming project's pyproject.toml: policy and knobs only, never a path
[tool.xtrax]
jax_compilation_cache = "on"                     # or "off" to opt this project out
jax_cache_min_compile_time_secs = 2.0            # store only compiles that cost something
jax_cache_max_size_bytes = 5_000_000_000         # LRU eviction (needs filelock)
from xtrax import jax_cache

setting = jax_cache.configure()   # CacheSetting(dir, source, enabled, policy, ...)

setting.source and setting.policy_source name the deciding layers. With nothing configured anywhere, xtrax leaves JAX's own settings alone. A configured off clears JAX's flag (JAX would otherwise read JAX_COMPILATION_CACHE_DIR=none as a directory named none). On a Slurm cluster, put the directory on a flash tier without a file-count cap, writable only by you. JAX treats cache entries as trusted code. Entries go under jaxlib-<version>/ inside the directory (JAX's key already includes the version, so this only makes pruning easy); jax_cache_namespace = "cpu-flags" adds a host-CPU-ISA segment for CPU executables shared across mixed nodes, and "none" uses the directory as given. JAX writes entries non-atomically, so a preempted write can leave a truncated entry; run jax_cache.prune_corrupt() between attempts. See the xtrax.jax_cache docstring for the knobs and file-count caveats.

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.1b9

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.1b9
File Size Uploaded Provenance Actions
xtrax-0.4.1b9.tar.gz 4.6 MB With provenance Details for xtrax-0.4.1b9.tar.gz

Built distribution (wheel)

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

Total release size: 5.5 MB

Release files / xtrax-0.4.1b9.tar.gz

Download URL xtrax-0.4.1b9.tar.gz
Size 4.6 MB
Tags Source
SHA-256 checksum
How to use checksums
242d7401dbf78d277c25e8ae823451937836423c4f8c4062e003e46701daccc1
BLAKE2b-256 checksum
How to use checksums
481c94a77e42d1f0b3ca5dd11362fc0a5426de083af12dd56095721fe6cad3ca
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 20, 2026.

Transparency log

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

Download URL xtrax-0.4.1b9-py3-none-any.whl
Size 984.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
67bcdbb5807f2bcc971e352da83b42573b4f63fdfac26f2fcdd76dd544e0049d
BLAKE2b-256 checksum
How to use checksums
63e0c69cb3f8b5eb8e7e48316260a9aac0ae8ef4131d25af4ddc8621ac3410e0
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 20, 2026.

Transparency log

Security for xtrax 0.4.1b9

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.1b9.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 20, 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