tlparse

library0.4.3pypypiunverified

tlparse is a command-line utility for parsing structured `TORCH_LOG` logs generated by PyTorch's `torch.compile`. It analyzes these logs and outputs rich HTML reports, aiding in understanding the compilation process, identifying graph breaks, recompilations, and debugging dynamic shape issues. The current version is 0.4.3, and it is actively maintained within the PyTorch ecosystem.

ai-ml

pip install tlparse

github ↗package ↗

INSTALL

IMPORT

SIG · TLPARSE

tlparse

ai-mlpythonv0.4.3

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

To use `tlparse`, first run your PyTorch script with the `TORCH_TRACE` environment variable set to a desired log directory. Then, execute the `tlparse` command-line tool on that directory to generate an HTML report. This example demonstrates how to set up log generation and provides the subsequent `tlparse` command.

import os import torch @torch.compile def my_model(x): return x + x def run_model_with_trace(): log_dir = os.path.join(os.getcwd(), "my_traced_log_dir") os.makedirs(log_dir, exist_ok=True) # Set TORCH_TRACE environment variable to collect logs os.environ['TORCH_TRACE'] = log_dir try: x = torch.randn(10, 10) _ = my_model(x) print(f"Logs generated in: {log_dir}") print(f"Now run: tlparse {log_dir} -o tl_out/ --latest") finally: # Clean up the environment variable after use del os.environ['TORCH_TRACE'] if __name__ == "__main__": run_model_with_trace()

tlparse --version

Debug

Known issues

breakingThe `parse_path` function signature changed in version 0.4.0 (from `ParseConfig` to `&ParseConfig`). This primarily affects developers extending `tlparse` with custom parsers in Rust, not typical Python users of the CLI.

fix

Update custom Rust parsers to match the new `parse_path` signature.

affects: >=0.4.0

gotcha`TORCH_TRACE` logs contain your model's source code. Exercise caution when sharing these logs as they can expose intellectual property, although they do not contain model weights.

fix

Review log contents before sharing, especially in public forums or bug reports. Consider anonymizing sensitive code sections if necessary.

affects: all

gotchaWhen submitting `tlparse` reports for bug fixes, simply attaching `index.html` is insufficient. The `index.html` only provides a catalogue; PyTorch developers typically need the entire `tl_out` directory (or a compressed archive of it) or the raw `TORCH_TRACE` log directory for full context.

fix

Always share the complete output directory (e.g., a zip of `tl_out/`) or the original `TORCH_TRACE` log directory.

affects: all

gotchatlparse helps identify performance bottlenecks like 'graph breaks' (light green frames) and 'recompilations' (frames like `[10/0] [10/1] [10/2]`) in `torch.compile` output. These indicate lost optimization opportunities and should be investigated.

fix

Simplify code, reduce data-dependent operations, or adopt compiler-friendly patterns in your PyTorch model to minimize graph breaks and recompilations. Consult PyTorch `torch.compile` documentation for best practices.

affects: all

Errors

Common errors & fixes

command not found: tlparse

The `tlparse` executable is not in your system's PATH, or the package was not installed correctly.

fix

Ensure `pip install tlparse` completed successfully and verify that your shell's PATH environment variable includes the directory where pip installs scripts (e.g., `~/.local/bin` on Linux/macOS or `C:\PythonXX\Scripts` on Windows).

tlparse /tmp/my_traced_log_dir --latest produces 'No logs found in /tmp/my_traced_log_dir.'

The `TORCH_TRACE` environment variable was not set correctly before running the PyTorch program, the program did not execute `torch.compile` pathways that generate logs, or `tlparse` is pointed to an empty or incorrect directory.

fix

Rerun your PyTorch script with `TORCH_TRACE="/tmp/my_traced_log_dir" python your_script.py`. Double-check that the specified directory exists and contains log files before running `tlparse` on it.

The tlparse output HTML report does not automatically open in my web browser.

The `tlparse` command-line tool attempts to open the browser, but this functionality might fail in certain execution environments (e.g., remote SSH sessions, CI/CD pipelines, or systems without a default browser configured).

fix

Manually navigate to the output directory (default is `tl_out/` relative to where `tlparse` was run) and open the `index.html` file in your preferred web browser.

Upgrade

Version history

0.4.3latest on PyPI · released Sep 12, 2025

Audit

Dependencies

No dependency data recorded yet.

Agent activity

17 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/ezyang/tlparse ↗

packagehttps://pypi.org/project/tlparse/ ↗