{"id":5553,"library":"xprof","title":"XProf Profiler Plugin","description":"XProf is a comprehensive profiling and performance analysis tool for machine learning workloads. It supports frameworks such as JAX, TensorFlow, and PyTorch/XLA, running on various hardware including CPUs, GPUs, and TPUs. The library offers a suite of tools like Overview, Trace Viewer, Memory Profile Viewer, and Graph Viewer to aid in understanding, debugging, and optimizing ML programs. It is actively maintained with frequent minor and patch releases.","status":"active","version":"2.22.1","language":"python","source_language":"en","source_url":"https://github.com/openxla/xprof","tags":["profiling","machine learning","jax","tensorflow","pytorch","xla","tpu","gpu","cpu","performance"],"install":[{"cmd":"pip install xprof","lang":"bash","label":"Basic installation"},{"cmd":"pip install xprof tensorboard","lang":"bash","label":"With TensorBoard plugin"}],"dependencies":[{"reason":"Optional: Provides a UI for visualizing profiles as an XProf plugin.","package":"tensorboard","optional":true},{"reason":"Direct dependency for certain profiling tools (HLO Op Profile, Trace Viewer, Graph Viewer) when profiling TPUs. Specific versions have known regressions.","package":"libtpu","optional":false}],"imports":[],"quickstart":{"code":"# 1. Collect profile data (example using JAX profiler, actual collection varies by framework)\n# In your ML training code (e.g., JAX):\n# import jax.profiler\n# jax.profiler.start_server(9012)\n# ... run your model ...\n# jax.profiler.stop_server()\n\n# 2. Run XProf as a standalone server to view collected profiles\n# Assuming profile data is saved to 'profiler/demo' directory:\n# To run XProf standalone:\nxprof --logdir=profiler/demo --port=6006\n\n# Or, to view with TensorBoard (if installed):\ntensorboard --logdir=profiler/demo","lang":"bash","description":"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."},"warnings":[{"fix":"As a temporary workaround, use `libtpu 0.0.36`. This issue has been acknowledged and is being resolved by the developers.","message":"A 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.","severity":"breaking","affected_versions":">=2.22.0"},{"message":"XProf 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.","severity":"gotcha"},{"fix":"Install an older version of setuptools: `pip install \"setuptools<70\"`.","message":"Python 3.12+ users may encounter a `ModuleNotFoundError: No module named 'pkg_resources'` during installation or runtime due to changes in Python's packaging system.","severity":"gotcha","affected_versions":">=2.20.0 (with Python 3.12+)"},{"fix":"Try 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`.","message":"When 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.","severity":"gotcha","affected_versions":"All versions, especially with older `tensorflow`/`tensorboard` dependencies."}],"env_vars":null,"search_vec":"'activ':63 'aid':53 'analysi':11 'comprehens':7 'cpu':80 'cpus':31 'debug':56 'framework':19 'frequent':66 'gpu':79 'gpus':32 'graph':50 'hardwar':29 'includ':30 'jax':22,74 'learn':15,73 'librari':36 'like':42 'machin':14,72 'maintain':64 'memori':46 'minor':67 'ml':59 'offer':37 'optim':58 'overview':43 'patch':69 'perform':10,81 'plugin':3 'profil':2,8,47,71 'program':60 'pytorch':76 'pytorch/xla':25 'releas':70 'run':26 'suit':39 'support':18 'tensorflow':23,75 'tool':12,41 'tpu':78 'tpus':34 'trace':44 'understand':55 'various':28 'viewer':45,48,51 'workload':16 'xla':77 'xprof':1,4","created_at":"2026-04-14T01:38:48.014864+00:00","updated_at":"2026-04-17T14:58:20.063649+00:00","problems":[{"fix":"Install the profiler plugin using pip: `pip install tensorflow-profiler`","cause":"The TensorBoard profiler plugin (which uses xprof internally) is not installed or not accessible in the current Python environment where TensorBoard is running.","error":"WARNING:tensorflow:Couldn't find tbp profiler plugin. Try 'pip install tensorflow-profiler'"},{"fix":"Increase 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.","cause":"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.","error":"No data collected. Try adjusting the profile duration or checking your configuration."},{"fix":"Ensure 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.","cause":"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.","error":"Failed to connect to the profiler agent."},{"fix":"Do 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.","cause":"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.","error":"ModuleNotFoundError: No module named 'xprof'"},{"fix":"Ensure 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.","cause":"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.","error":"No profiling data was collected."}],"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"xprof","cli_version":"usage: xprof [-h] [-l <logdir>] [-p <port>] [-hcpb] [--enable_tab_name_label]","type":"library","homepage":"https://xprof.dev","github":"https://github.com/openxla/xprof","docs":null,"changelog":null,"pypi":"https://pypi.org/project/xprof/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["ai-ml","observability"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-04-13","next_check":"2026-07-12","install_tag":null}}