[!IMPORTANT] XProf is hiring! Apply now at https://g.co/jobs/xprof

About

XProf offers a number of tools to analyse and visualize the performance of your model across multiple devices. Some of the tools include:

To learn more about the various XProf tools, check out the XProf documentation

[!TIP] New to profiling? Come and check out this Colab Demo.

Installation

To get the most recent release version of XProf, install it via pip:

$ pip install xprof

[!NOTE] For Python 3.12+ users, if you encounter ModuleNotFoundError: No module named 'pkg_resources', install an older version of setuptools:

pip install "setuptools<70"

Alternative installation options:

$ pip install xprof tensorboard

$ pip uninstall xprof tensorboard-plugin-profile
$ pip install xprof-nightly

sudo apt install ~/Downloads/bazelisk-amd64.deb

git clone https://github.com/openxla/xprof.git
cd xprof

bazel run --config=public_cache plugin:build_pip_package

cd /tmp/profile-pip
pip install .

Usage

[!IMPORTANT] XProf requires access to the Internet to load the Google Chart library. Some charts and tables may be missing if you run XProf entirely offline on your local machine, behind a corporate firewall, or in a datacenter.

Standalone

If you have profile data in a directory (e.g., profiler/demo), you can view it by running:

$ xprof --logdir=profiler/demo --port=6006

Or with the optional command name:

$ xprof server --logdir=profiler/demo --port=6006

With TensorBoard

If you have TensorBoard installed, you can run:

$ tensorboard --logdir=profiler/demo

If you are behind a corporate firewall, you may need to include the --bind_all tensorboard flag.

Go to localhost:6006/#profile of your browser, you should now see the demo overview page show up. Congratulations! You're now ready to capture a profile.

Command-Line Arguments

When launching the XProf server from the command line, you can use the following arguments:

¹ You can dynamically load profiles using session_path or run_path URL parameters, as described in the Log Directory Structure section.

Log Directory Structure

When using XProf, profile data must be placed in a specific directory structure. XProf expects .xplane.pb files to be in the following path:

<log_dir>/plugins/profile/<session_name>/

• <log_dir>: This is the root directory that you supply to tensorboard --logdir.
• plugins/profile/: This is a required subdirectory.
• <session_name>/: Each subdirectory inside plugins/profile/ represents a single profiling session. The name of this directory will appear in the TensorBoard UI dropdown to select the session.

Example:

If your log directory is structured like this:

/path/to/your/log_dir/
└── plugins/
    └── profile/
        ├── my_experiment_run_1/
        │   └── host0.xplane.pb
        └── benchmark_20251107/
            └── host1.xplane.pb

You would launch TensorBoard with:

tensorboard --logdir /path/to/your/log_dir/

The runs my_experiment_run_1 and benchmark_20251107 will be available in the "Sessions" tab of the UI.

You can also dynamically load sessions from a GCS bucket or local filesystem by passing URL parameters when loading XProf in your browser. This method works whether or not you provided a logdir at startup and is useful for viewing profiles from various locations without restarting XProf.

For example, if you start XProf with no log directory:

xprof server

You can load sessions using the following URL parameters.

Assume you have profile data stored on GCS or locally, structured like this:

gs://your-bucket/profile_runs/
├── my_experiment_run_1/
│   ├── host0.xplane.pb
│   └── host1.xplane.pb
└── benchmark_20251107/
    └── host0.xplane.pb

There are two URL parameters you can use:

• session_path: Use this to load a single session directly. The path should point to a directory containing .xplane.pb files for one session.

  • GCS Example: http://localhost:8791/?session_path=gs://your-bucket/profile_runs/my_experiment_run_1
  • Local Path Example: http://localhost:8791/?session_path=/path/to/profile_runs/my_experiment_run_1
  • Result: XProf will load the my_experiment_run_1 session, and you will see its data in the UI.

• run_path: Use this to point to a directory that contains multiple session directories.

  • GCS Example: http://localhost:8791/?run_path=gs://your-bucket/profile_runs/
  • Local Path Example: http://localhost:8791/?run_path=/path/to/profile_runs/
  • Result: XProf will list all session directories found under run_path (i.e., my_experiment_run_1 and benchmark_20251107) in the "Sessions" dropdown in the UI, allowing you to switch between them.

Loading Precedence

If multiple sources are provided, XProf uses the following order of precedence to determine which profiles to load:

1. session_path URL parameter
2. run_path URL parameter
3. logdir command-line argument

Distributed Profiling

[!WARNING] Currently, distributed processing only benefits the following tools: overview_page, framework_op_stats, input_pipeline, and pod_viewer.

XProf supports distributed profile processing by using an aggregator that distributes work to multiple XProf workers. This is useful for processing large profiles or handling multiple users.

[!NOTE] The ports used in these examples (6006 for the aggregator HTTP server, 9999 for the worker HTTP server, and 50051 for the worker gRPC server) are suggestions and can be customized.

Worker Node

Each worker node should run XProf with a gRPC port exposed so it can receive processing requests. You should also hide the capture button as workers are not meant to be interacted with directly.

$ xprof server --grpc_port=50051 --port=9999 --hide_capture_profile_button

Aggregator Node

The aggregator node runs XProf with the --worker_service_address flag pointing to all available workers. Users will interact with aggregator node's UI.

$ xprof server --worker_service_address=<worker1_ip>:50051,<worker2_ip>:50051 --port=6006 --logdir=profiler/demo

Replace <worker1_ip>, <worker2_ip> with the addresses of your worker machines. Requests sent to the aggregator on port 6006 will be distributed among the workers for processing.

For deploying a distributed XProf setup in a Kubernetes environment, see Kubernetes Deployment Guide.

Resources

• JAX Profiling Guide
• PyTorch/XLA Profiling Guide
• TensorFlow Profiling Guide
• Cloud TPU Profiling Guide
• Colab Tutorial
• Tensorflow Colab

Citing XProf

To cite XProf, please use the following BibTeX entry for the MLSys 2026 paper:

@inproceedings{1076558,
  title     = {XProf: An Open, Scalable and Extensible Profiling System for the Modern ML Stack},
  author    = {Robert Hundt and Naveen Kumar and Jose Baiocchi Paredes and Scott Goodson and Clive Verghese and Prasanna Rengasamy and Kelvin Le and Jiya Zhang and Charles Alaras and Yin Zhang and Kan Cai and Jiten Thakkar and Sai Ganesh Bandiatmakuri and Yogesh SY and Ani Udipi and Vikas Aggarwal},
  year      = {2026},
  booktitle = {Ninth Conference on Machine Learning and Systems}
}