Install & Compatibility
Where this runs
No compatibility data collected yet for this library.
Code
Verified usage
XProf is primarily used as a command-line tool or a TensorBoard plugin. First, ensure your machine learning workload is configured to capture profile data to a specified directory (e.g., `profiler/demo`). Then, launch XProf either as a standalone web server or through TensorBoard to visualize the collected profiles. The provided code demonstrates launching XProf from the command line, either directly or via TensorBoard.
# 1. Collect profile data (example using JAX profiler, actual collection varies by framework)
# In your ML training code (e.g., JAX):
# import jax.profiler
# jax.profiler.start_server(9012)
# ... run your model ...
# jax.profiler.stop_server()
# 2. Run XProf as a standalone server to view collected profiles
# Assuming profile data is saved to 'profiler/demo' directory:
# To run XProf standalone:
xprof --logdir=profiler/demo --port=6006
# Or, to view with TensorBoard (if installed):
tensorboard --logdir=profiler/demo
xprof --version
Debug
Known issues
breakingA known regression in `libtpu` versions `0.0.35` and `0.0.37` causes tools dependent on HLO Modules (e.g., HLO Op Profile, Trace Viewer, Graph Viewer) to not work as intended across all XProf versions. This significantly impacts core visualization features.fixAs a temporary workaround, use `libtpu 0.0.36`. This issue has been acknowledged and is being resolved by the developers.
affects: >=2.22.0
gotchaXProf requires internet access to load the Google Chart library. If running offline, behind a corporate firewall, or in a datacenter without external access, some charts and tables in the UI may be missing or fail to load.
gotchaPython 3.12+ users may encounter a `ModuleNotFoundError: No module named 'pkg_resources'` during installation or runtime due to changes in Python's packaging system.fixInstall an older version of setuptools: `pip install "setuptools<70"`.
affects: >=2.20.0 (with Python 3.12+)
gotchaWhen used with TensorBoard, version conflicts with the `protobuf` package (a common dependency for TensorFlow/TensorBoard) can lead to `TypeError: Descriptors cannot be created directly`. This indicates potential incompatibility with specific `tensorflow` or `tensorboard` versions.fixTry downgrading the `protobuf` package to `3.20.x` or lower, or set the environment variable `PROTOCOL_BUFFERS_PYTHON_IMPLEMENTATION=python` (though this might impact performance). Ensure your `tensorflow` and `tensorboard` versions are compatible with `xprof`.
affects: All versions, especially with older `tensorflow`/`tensorboard` dependencies.
Errors
Common errors & fixes
WARNING:tensorflow:Couldn't find tbp profiler plugin. Try 'pip install tensorflow-profiler'
The TensorBoard profiler plugin (which uses xprof internally) is not installed or not accessible in the current Python environment where TensorBoard is running.
fixInstall the profiler plugin using pip: `pip install tensorflow-profiler`
No data collected. Try adjusting the profile duration or checking your configuration.
The profiler ran but failed to capture any meaningful data, often due to an insufficient profiling duration, incorrect target host/port, or the profiled application not executing operations recognized by the profiler on supported hardware.
fixIncrease the profiling duration, ensure the target machine/TPU has the profiler agent running and is accessible, and verify that your ML framework (JAX, TensorFlow, PyTorch/XLA) is configured to generate profile data.
Failed to connect to the profiler agent.
The profiler agent on the target machine (e.g., TPU or remote server) is either not running, inaccessible due to network issues, or blocked by a firewall.
fixEnsure the profiler agent is started on the target machine with the correct IP address and port, verify network connectivity between your client and the target, and check firewall rules.
ModuleNotFoundError: No module named 'xprof'
The `xprof` library is not directly installable via `pip install xprof` nor is it intended for direct import as a top-level module. Its functionalities are typically exposed through TensorFlow's profiler API (`tf.profiler.experimental`), JAX's profiling tools, or via the TensorBoard Profiler plugin.
fixDo not attempt to `import xprof`. Instead, use the profiling APIs provided by your framework (e.g., `tf.profiler.experimental.start()`, `jax.profiler.start_trace()`) or launch TensorBoard (`tensorboard --logdir=your_log_dir`) and navigate to the Profiler tab after collecting trace data.
No profiling data was collected.
This message in the TensorBoard Profiler UI indicates that the profiling session either didn't run for a sufficient duration, the profiler couldn't capture any events, or the collected data was not saved correctly to the specified log directory, or the log directory is empty/incorrect.
fixEnsure your model's training loop runs for a sufficient number of steps within the `tf.profiler.experimental.start()` and `stop()` calls (or JAX/XLA equivalents). Verify that the `logdir` is correct, writeable, and matches the directory TensorBoard is monitoring. Check for any environment variable issues (e.g., `TF_CPP_MIN_LOG_LEVEL=0`) or hardware-specific setup requirements.
Upgrade
Version history
2.22.1latest on PyPI · released Apr 2, 2026
Audit
Dependencies
tensorboardoptionalOptional: Provides a UI for visualizing profiles as an XProf plugin.
libtpurequiredDirect dependency for certain profiling tools (HLO Op Profile, Trace Viewer, Graph Viewer) when profiling TPUs. Specific versions have known regressions.