{"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":"python","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,"search_vec":"'0.10.0':64 '17':68 '2026':69 'activ':72 'cadenc':76 'cli':4,15,82 'cloud':20,80 'command':12 'command-lin':11 'continu':58 'current':61 'cycl':38 'design':17 'detect':19 'develop':73 'devic':22 'diagnost':84 'duti':37 'extract':24 'googl':79 'google-cloud':78 'includ':33 'indic':70 'info':3,8 'insight':40 'interfac':14 'learn':87 'librari':30 'libtpu':29 'line':13 'live':54 'machin':86 'machine-learn':85 'march':67 'memori':34 'metric':26,32,83 'mode':56 'monitor':59,81 'one':49 'one-tim':48 'provid':39 'releas':65,75 'runtim':25 'snapshot':51 'static':47 'stream':55 'support':45 'time':50 'tool':5,16 'tpu':2,7,21,42,77 'tpu-info':1,6 'usag':35 'util':43 'version':62","created_at":"2026-04-11T09:29:30.515396+00:00","updated_at":"2026-04-16T23:08:30.444614+00:00","problems":[{"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.","cause":"The `tpu-info` executable is not installed or its installation directory is not included in the system's PATH environment variable.","error":"tpu-info: command not found"},{"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.","cause":"The `tpu-info` tool cannot find or load the `libtpu.so` library, which is essential for communicating with TPU devices.","error":"Failed to open libtpu.so"},{"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).","cause":"The `tpu-info` tool was unable to detect any available TPU devices in the current execution environment.","error":"ERROR: No TPU device found"},{"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.","cause":"The user executing `tpu-info` lacks the necessary permissions to access the underlying TPU devices or their associated system resources.","error":"Permission denied"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"tpu-info","cli_version":"ERROR: libtpu not found.","type":"library","homepage":null,"github":"https://github.com/AI-Hypercomputer/cloud-accelerator-diagnostics","docs":null,"changelog":null,"pypi":"https://pypi.org/project/tpu-info/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["gcp","observability","devops","ai-ml"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-04-11","next_check":"2026-07-10","install_tag":null}}