{"id":4799,"library":"tensorboard-plugin-profile","title":"XProf Profiler Plugin","description":"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.","status":"active","version":"2.22.1","language":"en","source_language":"en","source_url":"https://github.com/openxla/xprof","tags":["profiling","tensorboard","machine-learning","xprof","tensorflow","pytorch","jax","performance-optimization","debugger"],"install":[{"cmd":"pip install tensorboard-plugin-profile","lang":"bash","label":"Install latest stable version"}],"dependencies":[{"reason":"Required as the host application for the plugin. Version >= 2.18.0 recommended.","package":"tensorboard","optional":false},{"reason":"Required for profiling TensorFlow models. Version >= 2.18.0 recommended.","package":"tensorflow","optional":true},{"reason":"Specific versions (0.0.35, 0.0.37) have known regressions affecting HLO-related tools. Version 0.0.36 is a recommended workaround.","package":"libtpu","optional":true},{"reason":"Required for GPU profiling. Specific CUDA/CUPTI versions may be needed.","package":"NVIDIA GPU drivers and CUDA Toolkit","optional":true}],"imports":[],"quickstart":{"code":"import tensorflow as tf\nfrom datetime import datetime\nimport os\n\n# Ensure log directory exists\nlog_dir = os.path.join(\"logs\", \"profile\", datetime.now().strftime(\"%Y%m%d-%H%M%S\"))\nos.makedirs(log_dir, exist_ok=True)\n\n# Dummy model and data for profiling\nmodel = tf.keras.models.Sequential([\n    tf.keras.layers.Dense(10, activation='relu', input_shape=(10,)),\n    tf.keras.layers.Dense(1, activation='sigmoid')\n])\nmodel.compile(optimizer='adam', loss='binary_crossentropy')\ndata = tf.random.normal(shape=(100, 10))\nlabels = tf.random.uniform(shape=(100, 1), maxval=2, dtype=tf.int64)\n\n# Option 1: Programmatic profiling with tf.profiler.experimental\nprint(f\"Starting programmatic profile, data will be in {log_dir}\")\nwith tf.profiler.experimental.Profile(log_dir):\n    model.fit(data, labels, epochs=2, batch_size=32)\n\n# Option 2: Using TensorBoard Keras Callback for profiling specific batches\n# tb_callback = tf.keras.callbacks.TensorBoard(\n#     log_dir=log_dir,\n#     profile_batch='1,3' # Profile batches 1 to 3\n# )\n# model.fit(data, labels, epochs=2, batch_size=32, callbacks=[tb_callback])\n\nprint(\"Profiling data generated. To view, run TensorBoard in your terminal:\")\nprint(f\"tensorboard --logdir={os.path.abspath('logs')}\")\nprint(\"Then open your browser to http://localhost:6006/#profile\")\n","lang":"python","description":"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."},"warnings":[{"fix":"Downgrade or upgrade `libtpu` to `0.0.36` or wait for a fix in newer `libtpu` versions.","message":"A 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.","severity":"gotcha","affected_versions":"XProf v2.22.0 onwards (when used with affected libtpu versions)"},{"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.","message":"The 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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Always install `tensorboard` and `tensorboard-plugin-profile` in the same virtual environment and ensure it's activated before launching TensorBoard.","message":"When 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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Upgrade TensorFlow and TensorBoard to versions `2.18.0` or newer: `pip install --upgrade tensorflow tensorboard`.","message":"The 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.","severity":"breaking","affected_versions":"< 2.18.0"},{"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`.","message":"For 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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Limit profiling duration or step range (e.g., `profile_batch='10,15'` in Keras callback) and skip initial warm-up steps.","message":"Running 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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-12T00:00:00.000Z","next_check":"2026-07-11T00:00:00.000Z"}