tpu-info

library0.10.0pypypiunverified

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.

gcp observability devops ai-ml

pip install tpu-info

github ↗package ↗

INSTALL

IMPORT

SIG · TPU-INFO

tpu-info

gcppythonv0.10.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

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

tpu-info --version

Debug

Known issues

gotchatpu-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`.

affects: All versions

breakingOutdated 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.

affects: <= 0.8.0 and older libtpu versions

deprecatedVersions 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.

affects: < 0.8.1

Errors

Common errors & fixes

tpu-info: command not found

The `tpu-info` executable is not installed or its installation directory is not included in the system's PATH environment variable.

fix

Install the `tpu-info` package using `pip install tpu-info` and ensure your user's script directory (e.g., `~/.local/bin`) is in your PATH.

Failed to open libtpu.so

The `tpu-info` tool cannot find or load the `libtpu.so` library, which is essential for communicating with TPU devices.

fix

Ensure `libtpu.so` is installed and its path is included in the `LD_LIBRARY_PATH` environment variable, typically by setting up a correct JAX/TPU environment.

ERROR: No TPU device found

The `tpu-info` tool was unable to detect any available TPU devices in the current execution environment.

fix

Verify that a TPU device is properly provisioned and accessible from your environment (e.g., running in a TPU VM or a container configured for TPU access).

Permission denied

The user executing `tpu-info` lacks the necessary permissions to access the underlying TPU devices or their associated system resources.

fix

Ensure the user has appropriate permissions to interact with TPU resources; if on a system with direct hardware access, this might involve running with `sudo` or adding the user to a specific group.

Upgrade

Version history

0.10.0latest on PyPI · released Mar 17, 2026

Audit

Dependencies

libtpurequiredtpu-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].

JAX or PyTorch/XLArequiredTo view current TPU utilization data, tpu-info requires a running TPU workload with a supported ML framework such as JAX or PyTorch/XLA.

Agent activity

37 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/AI-Hypercomputer/cloud-accelerator-diagnostics ↗

packagehttps://pypi.org/project/tpu-info/ ↗