tpu-info CLI Tool

0.10.0 · active · verified Sat Apr 11

tpu-info is a command-line interface (CLI) tool designed for detecting Cloud TPU devices and extracting runtime metrics from the `libtpu` library. These metrics include memory usage and duty cycle, providing insights into TPU utilization. It supports both static, one-time snapshots and a live streaming mode for continuous monitoring. The current version is 0.10.0, released on March 17, 2026, indicating an active development and release cadence.

Warnings

gotcha tpu-info will not display any utilization data if there is no active TPU workload running with a supported ML framework (like JAX or PyTorch/XLA). Ensure your model is actively processing data on the TPU.
Fix: Start a machine learning workload on your TPU using a compatible framework (e.g., `import jax; _ = jax.numpy.ones((large_size, large_size))` or `import torch_xla; _ = torch.randn(..., device=torch_xla.device())`) before running `tpu-info`.
breaking Outdated versions of `tpu-info` or the underlying `libtpu` library may be missing new metrics and features, or might be incompatible with your environment. Releases from before 2024, in particular, may have compatibility issues.
Fix: Regularly update `tpu-info` to the latest version using `pip install --upgrade tpu-info`. Ensure your `libtpu` installation is also up-to-date and compatible with your environment by checking `tpu-info --version` output.
deprecated Versions of `tpu-info` prior to 0.8.1 might trigger a `DeprecationWarning` in Python 3.11+ due to issues related to `enum` classes.
Fix: Upgrade to `tpu-info` version 0.8.1 or newer (`pip install --upgrade tpu-info`) to resolve the `DeprecationWarning` in Python 3.11 and later environments.

Install

pip install tpu-info Install latest release
pip install git+https://github.com/google/cloud-accelerator-diagnostics/#subdirectory=tpu_info Install from source

Quickstart

To use `tpu-info`, you must have an active workload running on your Cloud TPU with a supported machine learning framework (e.g., JAX or PyTorch/XLA). Once a workload is active, simply execute `tpu-info` in your terminal to get a one-time snapshot of the metrics. You can add the `--streaming` flag for continuous monitoring.

# First, ensure a JAX or PyTorch/XLA workload is running on your Cloud TPU.
# Example with JAX (run this in a Python environment connected to TPU):
# import jax
# import jax.numpy as jnp
# t = jnp.ones((1000, 1000)) # This creates an active workload on TPU

# Then, on the same machine, open a new terminal and run:
tpu-info

view raw JSON →