Skip to content

01. Installation

Jump to bottom
Yueming Hao edited this page Jul 10, 2025 · 9 revisions

This guide covers all installation scenarios for TritonParse, from basic usage to full development setup.

🎯 Installation Options

Option 1: Basic User Installation (Recommended)

For users who only need to generate traces and use the web interface

Option 2: Website Development Setup

For contributors working on the web interface

Option 3: Full Development Setup

For core contributors working on Python code

📋 Prerequisites

System Requirements

  • Python >= 3.10
  • Operating System: Linux, macOS, or Windows (with WSL recommended)
  • CUDA (for GPU tracing): Compatible NVIDIA GPU with CUDA support
  • Node.js >= 18.0.0 (for website development only)

Required: Triton Installation

Important: You need Triton > 3.3.1 or compiled from source.

# Install Triton from source (required)
git clone https://github.com/triton-lang/triton.git
cd triton
pip install -e .

For detailed Triton installation instructions, see the official Triton documentation.

🚀 Option 1: Basic User Installation

Perfect for users who want to generate traces and use the web interface.

Step 1: Clone Repository

git clone https://github.com/pytorch-labs/tritonparse.git
cd tritonparse

Step 2: Install TritonParse

# Install in development mode
pip install -e .

# Or install with test dependencies
pip install -e ".[test]"

Step 3: Verify Installation

# Test with the included example
cd tests
TORCHINDUCTOR_FX_GRAPH_CACHE=0 python test_add.py

Expected output:

Triton kernel executed successfully
Torch compiled function executed successfully
tritonparse log file list: /tmp/tmp1gan7zky/log_file_list.json
INFO:tritonparse:Copying parsed logs from /tmp/tmp1gan7zky to /scratch/findhao/tritonparse/tests/parsed_output

================================================================================
📁 TRITONPARSE PARSING RESULTS
================================================================================
📂 Parsed files directory: /scratch/findhao/tritonparse/tests/parsed_output
📊 Total files generated: 2

📄 Generated files:
--------------------------------------------------
   1. 📝 dedicated_log_triton_trace_findhao__mapped.ndjson.gz (7.2KB)
   2. 📝 log_file_list.json (181B)
================================================================================
✅ Parsing completed successfully!
================================================================================

Step 4: Use the Web Interface

  1. Generate trace files using the Python API
  2. Visit https://pytorch-labs.github.io/tritonparse/
  3. Load your trace files (.ndjson or .gz format)

🌐 Option 2: Website Development Setup

For contributors working on the React-based web interface.

Prerequisites

  • Node.js >= 18.0.0
  • npm (comes with Node.js)

Step 1: Basic Installation

Follow Option 1 first.

Step 2: Install Website Dependencies

cd website
npm install

Step 3: Start Development Server

npm run dev

Access the development server at http://localhost:5173

Step 4: Available Development Commands

# Development server
npm run dev

# Production build
npm run build

# Standalone HTML build (single file)
npm run build:single

# Linting
npm run lint

# Preview production build
npm run preview

🔧 Option 3: Full Development Setup

For core contributors working on Python code, including formatting and testing.

Step 1: Basic Installation

Follow Option 1 first.

Step 2: Install Development Dependencies

# Install all development dependencies including formatting tools
make install-dev

This installs:

  • black - Code formatting
  • usort - Import sorting
  • ruff - Linting

Step 3: Verify Development Setup

# Check code formatting
make format-check

# Run linting
make lint-check

# Run tests
python -m unittest tests.test_tritonparse -v

Step 4: Website Development (Optional)

cd website
npm install
npm run dev

🛠️ Development Commands

Python Development

# Format code
make format

# Check formatting
make format-check

# Run linting
make lint-check

# Run tests
python -m unittest tests.test_tritonparse -v

# Run specific test
python -m unittest tests.test_tritonparse.TestTritonparseCUDA.test_whole_workflow -v

Website Development

cd website

# Development server
npm run dev

# Build for production
npm run build

# Lint frontend code
npm run lint

🐛 Troubleshooting

Common Issues

1. Triton Installation Issues

# Error: "No module named 'triton'"
# Solution: Install Triton from source
git clone https://github.com/triton-lang/triton.git
cd triton
pip install -e .

2. CUDA Not Available

# Error: "CUDA not available"
# Check CUDA installation
python -c "import torch; print(torch.cuda.is_available())"

# If False, install CUDA-enabled PyTorch
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118

3. Permission Issues

# Error: Permission denied
# Use virtual environment
python -m venv tritonparse-env
source tritonparse-env/bin/activate  # Linux/Mac
# or
tritonparse-env\Scripts\activate  # Windows

4. Formatting Tool Issues

# Error: "black not found"
# Reinstall development dependencies
make install-dev

# Or install manually
pip install black usort ruff

5. Website Build Issues

# Error: "Node.js version too old"
# Update Node.js to >= 18.0.0
nvm install 18
nvm use 18

# Clear cache and reinstall
rm -rf node_modules package-lock.json
npm install

Environment Variables

Set these for development:

# Enable debug logging
export TRITONPARSE_DEBUG=1

# Enable NDJSON output (default)
export TRITONPARSE_NDJSON=1

# Enable gzip compression
export TRITON_TRACE_GZIP=1

# Custom trace directory
export TRITON_TRACE=/path/to/traces

# Disable FX graph cache (for testing)
export TORCHINDUCTOR_FX_GRAPH_CACHE=0

Getting Help

If you encounter issues:

  1. Check the Troubleshooting Guide for common solutions
  2. Review the FAQ for frequently asked questions
  3. Search GitHub Issues for existing solutions
  4. Open a new issue with:
    • Your system information (python --version, pip list)
    • Complete error messages
    • Steps to reproduce the issue

✅ Installation Verification

After installation, verify everything works:

1. Python API Test

import tritonparse.structured_logging
import tritonparse.utils

# Should not raise any errors
print("TritonParse installed successfully!")

2. Test with Example

cd tests
TORCHINDUCTOR_FX_GRAPH_CACHE=0 python test_add.py

3. Web Interface Test

  1. Load the example trace file from tests/example_output/
  2. Visit https://pytorch-labs.github.io/tritonparse/
  3. Upload and visualize the trace

4. Development Tools Test (if installed)

# Should all pass without errors
make format-check
make lint-check
python -m unittest tests.test_tritonparse.TestTritonparseCPU -v

🚀 Next Steps

After successful installation:

  1. Read the Usage Guide to learn how to generate traces
  2. Explore the Web Interface Guide to master the visualization
  3. Check out Basic Examples for practical usage scenarios
  4. Join the GitHub Discussions for community support
Clone this wiki locally