{"id":3298,"library":"tpu-info","title":"tpu-info CLI Tool","description":"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.","status":"active","version":"0.10.0","language":"en","source_language":"en","source_url":"https://github.com/google/cloud-accelerator-diagnostics/tree/main/tpu_info","tags":["tpu","google-cloud","monitoring","cli","metrics","diagnostics","machine-learning"],"install":[{"cmd":"pip install tpu-info","lang":"bash","label":"Install latest release"},{"cmd":"pip install git+https://github.com/google/cloud-accelerator-diagnostics/#subdirectory=tpu_info","lang":"bash","label":"Install from source"}],"dependencies":[{"reason":"tpu-info reads runtime metrics from the libtpu library. While not a direct pip dependency, a compatible libtpu version is essential for functionality. libtpu is often installed as a dependency with machine learning frameworks like jax[tpu].","package":"libtpu","optional":false},{"reason":"To view current TPU utilization data, tpu-info requires a running TPU workload with a supported ML framework such as JAX or PyTorch/XLA.","package":"JAX or PyTorch/XLA","optional":false}],"imports":[],"quickstart":{"code":"# First, ensure a JAX or PyTorch/XLA workload is running on your Cloud TPU.\n# Example with JAX (run this in a Python environment connected to TPU):\n# import jax\n# import jax.numpy as jnp\n# t = jnp.ones((1000, 1000)) # This creates an active workload on TPU\n\n# Then, on the same machine, open a new terminal and run:\ntpu-info","lang":"bash","description":"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."},"warnings":[{"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`.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"breaking","affected_versions":"<= 0.8.0 and older libtpu versions"},{"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.","message":"Versions of `tpu-info` prior to 0.8.1 might trigger a `DeprecationWarning` in Python 3.11+ due to issues related to `enum` classes.","severity":"deprecated","affected_versions":"< 0.8.1"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}