Registry / ai-ml / tensorboard-plugin-profile

tensorboard-plugin-profile

JSON →
library2.22.1pypypiunverified

The XProf Profiler Plugin is a powerful tool for profiling and performance analysis of machine learning models across various frameworks, including TensorFlow, JAX, and PyTorch/XLA. It helps users understand, debug, and optimize their programs to run efficiently on CPUs, GPUs, and TPUs. The current version is 2.22.1, and the library follows the TensorFlow versioning scheme, with frequent updates and releases.

pip install tensorboard-plugin-profile
INSTALL
IMPORT
SIG · TENSORBOARD-PLUGIN
T
tensorboard-plugin-profile
ai-mlpythonv2.22.1
harness data pending
Install & Compatibility
Where this runs

No compatibility data collected yet for this library.

Code
Verified usage

This quickstart demonstrates how to generate profiling data for a TensorFlow model and then launch TensorBoard to visualize it. The `tensorboard-plugin-profile` automatically integrates with TensorBoard once installed. After running the Python code, open a new terminal and execute the `tensorboard` command provided to view the profile data in your browser under the 'Profile' tab.

import tensorflow as tf from datetime import datetime import os # Ensure log directory exists log_dir = os.path.join("logs", "profile", datetime.now().strftime("%Y%m%d-%H%M%S")) os.makedirs(log_dir, exist_ok=True) # Dummy model and data for profiling model = tf.keras.models.Sequential([ tf.keras.layers.Dense(10, activation='relu', input_shape=(10,)), tf.keras.layers.Dense(1, activation='sigmoid') ]) model.compile(optimizer='adam', loss='binary_crossentropy') data = tf.random.normal(shape=(100, 10)) labels = tf.random.uniform(shape=(100, 1), maxval=2, dtype=tf.int64) # Option 1: Programmatic profiling with tf.profiler.experimental print(f"Starting programmatic profile, data will be in {log_dir}") with tf.profiler.experimental.Profile(log_dir): model.fit(data, labels, epochs=2, batch_size=32) # Option 2: Using TensorBoard Keras Callback for profiling specific batches # tb_callback = tf.keras.callbacks.TensorBoard( # log_dir=log_dir, # profile_batch='1,3' # Profile batches 1 to 3 # ) # model.fit(data, labels, epochs=2, batch_size=32, callbacks=[tb_callback]) print("Profiling data generated. To view, run TensorBoard in your terminal:") print(f"tensorboard --logdir={os.path.abspath('logs')}") print("Then open your browser to http://localhost:6006/#profile")
Debug
Known issues
gotchaA regression in `libtpu` versions `0.0.35` and `0.0.37` affects HLO Module-dependent tools like 'HLO Op Profile', 'Trace Viewer', and 'Graph Viewer' in XProf. It is recommended to use `libtpu 0.0.36` as a temporary workaround.
fix
Downgrade or upgrade `libtpu` to `0.0.36` or wait for a fix in newer `libtpu` versions.
affects: XProf v2.22.0 onwards (when used with affected libtpu versions)
gotchaThe TensorBoard Profiler Plugin requires internet access to load the Google Chart library. If running TensorBoard offline, behind a corporate firewall, or in a datacenter, some charts and tables in the profiler interface may not display correctly.
fix
Ensure internet connectivity or configure firewall rules to allow access to Google Chart libraries. For corporate environments, consider using the `--bind_all` TensorBoard flag if applicable.
affects: All versions
gotchaWhen using virtual environments, ensure that both `TensorBoard` and `tensorboard-plugin-profile` are installed within the *same and activated* virtual environment. Mixing installations or not activating the environment can lead to the profiler tab not appearing or displaying a 'plugin has moved' error.
fix
Always install `tensorboard` and `tensorboard-plugin-profile` in the same virtual environment and ensure it's activated before launching TensorBoard.
affects: All versions
breakingThe Profiler plugin requires recent versions of TensorFlow and TensorBoard. Specifically, `TensorFlow >= 2.18.0` and `TensorBoard >= 2.18.0` are prerequisites. Older versions may lead to compatibility issues, including 'The profile plugin has moved' messages even after installation.
fix
Upgrade TensorFlow and TensorBoard to versions `2.18.0` or newer: `pip install --upgrade tensorflow tensorboard`.
affects: < 2.18.0
gotchaFor GPU profiling, the NVIDIA CUDA Profiling Tools Interface (CUPTI) must be correctly configured and accessible via the `LD_LIBRARY_PATH` environment variable. Insufficient privileges or an incorrect path can prevent GPU profiling data collection.
fix
Verify CUPTI installation and path using `/sbin/ldconfig -N -v $(sed 's/:/ /g' <<< $LD_LIBRARY_PATH) | grep libcupti`. If not found, prepend its installation directory (e.g., `/usr/local/cuda/extras/CUPTI/lib64`) to `LD_LIBRARY_PATH`.
affects: All versions
gotchaRunning the profiler for excessively long durations can lead to out-of-memory errors. It is recommended to profile no more than 10 steps at a time. Also, avoid profiling the first few batches of training, as initialization overhead can skew results.
fix
Limit profiling duration or step range (e.g., `profile_batch='10,15'` in Keras callback) and skip initial warm-up steps.
affects: All versions
Errors
Common errors & fixes
Could not load plugin profiler from tensorflow.tensorboard.plugins.profile.profile_plugin.
The tensorboard-plugin-profile package is either not installed or there is a version mismatch between tensorflow, tensorboard, and the plugin.
fix
Ensure all related packages are installed and compatible: `pip install --upgrade tensorflow tensorboard tensorboard-plugin-profile`
No profile data was found.
This message appears in the TensorBoard UI when the TensorFlow profiler was either not correctly started/stopped, no profile events were captured, or TensorBoard is monitoring the wrong log directory.
fix
Verify that `tf.profiler.experimental.start()` and `tf.profiler.experimental.stop()` are correctly implemented in your code, that your `logdir` is correct, and that your model is actually executing operations during the profiling window.
ModuleNotFoundError: No module named 'tensorboard_plugin_profile'
The `tensorboard-plugin-profile` package is not installed in the active Python environment from which TensorBoard is launched.
fix
Install the package using pip: `pip install tensorboard-plugin-profile`
AttributeError: module 'tensorflow.profiler' has no attribute 'start'
The code is attempting to use an outdated or incorrect API for the TensorFlow profiler; the recommended API is `tf.profiler.experimental`.
fix
Update your profiling code to use the modern `tf.profiler.experimental` API for starting and stopping the profiler:
```python
import tensorflow as tf
logdir = "logs/profile/"
tf.profiler.experimental.start(logdir)
# Your model training/inference code
tf.profiler.experimental.stop()
```
Upgrade
Version history
2.22.1latest on PyPI · released Apr 2, 2026
Audit
Dependencies
tensorboardrequiredRequired as the host application for the plugin. Version >= 2.18.0 recommended.
tensorflowoptionalRequired for profiling TensorFlow models. Version >= 2.18.0 recommended.
libtpuoptionalSpecific versions (0.0.35, 0.0.37) have known regressions affecting HLO-related tools. Version 0.0.36 is a recommended workaround.
NVIDIA GPU drivers and CUDA ToolkitoptionalRequired for GPU profiling. Specific CUDA/CUPTI versions may be needed.
Agent activity
33 hits · last 30 days
node
28
OpenAI (training)
1
Resources
tensorboard-plugin-profile — pip install tensorboard-plugin-profile · libregistry