Registry /
ai-ml / tensorboard-plugin-profile
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.fixDowngrade 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.fixEnsure 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.fixAlways 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.fixUpgrade 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.fixVerify 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.fixLimit 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.
fixEnsure 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.
fixVerify 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.
fixInstall 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`.
fixUpdate 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.