This release is a pre-release and may not be stable for production use.
XProf (+ Tensorboard Profiler Plugin)
An open, scalable, and extensible profiler for the modern ML stack.
About ✧ Installation ✧ Usage ✧ Resources ✧ Citing
About
XProf offers a number of tools to analyse and visualize the performance of your model across multiple devices. Some of the tools include:
Overview PageA high-level overview of the performance of your model. This is an aggregated overview for your host and all devices. It includes:
|
Trace ViewerDisplays a timeline of the execution of your model that shows:
|
Memory ProfileMonitors the memory usage of your model. |
Graph ViewerA visualization of the graph structure of HLOs of your model. |
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
Alternative installation options:
Installation with Tensorboard
$ pip install xprof tensorboard
Google Cloud
If you use Google Cloud to run your workloads, we recommend the xprofiler tool.It provides a streamlined profile collection and viewing experience using VMs running XProf.
Nightly Releases
Every night, a nightly version of the package is released under the name of
xprof-nightly. This package contains the latest changes made by the XProf
developers.
To install the nightly version of profiler:
$ pip uninstall xprof tensorboard-plugin-profile
$ pip install xprof-nightly
Build from Source
If the pip packages don't work, you can build XProf from source using Bazel.
1. Set up Bazel
Bazel is the build system used for XProf. Bazelisk is a wrapper for Bazel that
simplifies Bazel version management. Download the appropriate .deb package for
your system from the Bazelisk releases
page and install the
downloaded package:
sudo apt install ~/Downloads/bazelisk-amd64.deb
2. Obtain the Repository
Clone the XProf GitHub repository to your local machine:
git clone https://github.com/openxla/xprof.git
cd xprof
3. Build the Project
Build the pip Package: Use Bazel to build the XProf pip package:
bazel run --config=public_cache plugin:build_pip_package
Navigate to the Bazel Output Directory and install:
cd /tmp/profile-pip
pip install .
Building on macOS (Apple Silicon)
On macOS the native profiler extension must be built explicitly, pinning the
SDK and minimum OS version. Building without these flags fails with errors such
as an xcrun SDK macosx10.11 that cannot be located and undefined symbols
(_PyModule_Create2). The following invocation is verified on Apple Silicon:
bazel build --config=macos --config=public_cache --macos_sdk_version=$(xcrun --show-sdk-version) --macos_minimum_os=13.0 //xprof/pywrap:profiler_plugin_c_api.so
Usage
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:
| Command | Shorthand | Default | Description |
|---|---|---|---|
--logdir <path> |
-l <path> |
The directory containing XProf profile data (files ending in .xplane.pb). If provided, XProf will load and display profiles from this directory. If omitted, XProf will start without loading any profiles.1 | |
--port <port> |
-p <port> |
8791 |
The port for the XProf web server. |
--grpc_port <port> |
-g <port> |
50051 |
The port for the gRPC server used for distributed processing. This must be different from --port. |
--worker_service_address <addresses> |
-w <addresses> |
0.0.0.0:<grpc_port> |
A comma-separated list of worker addresses (e.g., host1:50051,host2:50051) for distributed processing. |
--hide_capture_profile_button |
-h |
N/A | If set, hides the 'Capture Profile' button in the UI. |
--enable_tab_name_label |
-e |
False |
If set, shows a per-tab name label in the UI. |
--src_prefix <prefix> |
-s <prefix> |
A prefix prepended to source file paths, used for source-code linking in the UI. | |
--max_concurrent_worker_requests <n> |
-m <n> |
1 |
The maximum number of concurrent requests a worker's gRPC server will process, used in distributed profiling. |
1 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 totensorboard --logdir.plugins/profile/: This is a required subdirectory.<session_name>/: Each subdirectory insideplugins/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.pbfiles 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_1session, and you will see its data in the UI.
- GCS Example:
-
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_1andbenchmark_20251107) in the "Sessions" dropdown in the UI, allowing you to switch between them.
- GCS Example:
Loading Precedence
If multiple sources are provided, XProf uses the following order of precedence to determine which profiles to load:
session_pathURL parameterrun_pathURL parameterlogdircommand-line argument
Distributed Profiling
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.
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}
}
4 maintainers
Metadata
4 maintainers
Release files for xprof-nightly 2.24.2a20261010
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Built distributions (wheels)
| File | Reset | |||
|---|---|---|---|---|
| xprof_nightly-2.24.2a20261010-py3-none-win_amd64.whl | Python 3 | none | Windows x86-64 | Details |
| xprof_nightly-2.24.2a20261010-py3-none-manylinux_2_35_aarch64.whl | Python 3 | none | Linux glibc 2.35+ ARM64 | Details |
| xprof_nightly-2.24.2a20261010-py3-none-manylinux_2_27_x86_64.whl | Python 3 | none | Linux glibc 2.27+ x86-64 | Details |
| xprof_nightly-2.24.2a20261010-py3-none-macosx_11_0_arm64.whl | Python 3 | none | macOS 11.0+ ARM64 | Details |
Total release size: 148.6 MB
Release files / xprof_nightly-2.24.2a20261010-py3-none-win_amd64.whl
| Download URL | xprof_nightly-2.24.2a20261010-py3-none-win_amd64.whl |
|---|---|
| Size | 24.5 MB |
| Tags | Python 3 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
33034404012884b9b69175f169f93ce2819be145126da2bb5c108411b9d1b158
|
|
BLAKE2b-256 checksum How to use checksums |
6abbfbb99c2010108946e545a600c405e399a1aa30a457120108a913dcc68977
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.12.14
|
Release files / xprof_nightly-2.24.2a20261010-py3-none-manylinux_2_35_aarch64.whl
| Download URL | xprof_nightly-2.24.2a20261010-py3-none-manylinux_2_35_aarch64.whl |
|---|---|
| Size | 46.9 MB |
| Tags | Linux glibc 2.35+ ARM64 Python 3 |
|
SHA-256 checksum How to use checksums |
476b4bbe90b5b9bc6b9d67d4999a42a1b87987d98022e86f54d7a7ea44653a30
|
|
BLAKE2b-256 checksum How to use checksums |
55977bbfd6180626deda00df08318e1ce7c782b243ba911c21ecb7787ca1a480
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.12.14
|
Release files / xprof_nightly-2.24.2a20261010-py3-none-manylinux_2_27_x86_64.whl
| Download URL | xprof_nightly-2.24.2a20261010-py3-none-manylinux_2_27_x86_64.whl |
|---|---|
| Size | 32.0 MB |
| Tags | Linux glibc 2.27+ x86-64 Python 3 |
|
SHA-256 checksum How to use checksums |
63e5b8e89b4b5d8e677026a71e2f8b44a07720fbfb628e072762f0a6a7789921
|
|
BLAKE2b-256 checksum How to use checksums |
7fc571fd11875aea170dd5cbddc667a70d0c24112e45dd0a195cbae13895f0c6
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.12.14
|
Release files / xprof_nightly-2.24.2a20261010-py3-none-macosx_11_0_arm64.whl
| Download URL | xprof_nightly-2.24.2a20261010-py3-none-macosx_11_0_arm64.whl |
|---|---|
| Size | 45.1 MB |
| Tags | Python 3 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
9ec4235daf3609af50c32a091258850c1b9423541f4d1e763df8e6978e92a1ee
|
|
BLAKE2b-256 checksum How to use checksums |
4b54eab1e81b22c945ca681dad03eb3f2223259e58449f12f696e0329fd9323c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.12.14
|
