Skip to content

01. Installation

Jump to bottom
Yueming Hao edited this page Jul 10, 2025 · 4 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)
  • GPU Required (Triton depends on GPU):
    • NVIDIA GPUs: CUDA 11.8+ or 12.x
    • AMD GPUs: ROCm 5.0+ (supports MI100, MI200, MI300 series)
  • Node.js >= 18.0.0 (for website development only)

⚠️ Important: GPU is required to generate traces because Triton kernels can only run on GPU hardware. The web interface can view existing traces without GPU.

Required Dependencies

  • PyTorch with GPU support (we recommend PyTorch nightly for best compatibility)
    • For NVIDIA GPUs: PyTorch with CUDA support
    • For AMD GPUs: PyTorch with ROCm support
  • Triton > 3.3.1 (must be compiled from source for TritonParse compatibility)

💡 Note: Detailed installation instructions for these dependencies are provided in each installation option below.

🚀 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 PyTorch with GPU Support

For NVIDIA GPUs (CUDA)

# Install PyTorch nightly with CUDA 12.8 support (recommended)
pip install --pre torch torchvision torchaudio --index-url https://download.pytorch.org/whl/nightly/cu128

# Alternative: Install stable PyTorch with CUDA support
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118

# Verify PyTorch installation
python -c "import torch; print(f'PyTorch version: {torch.__version__}')"
python -c "import torch; print(f'CUDA available: {torch.cuda.is_available()}')"

For AMD GPUs (ROCm)

# Install PyTorch nightly with ROCm support (recommended)
pip install --pre torch torchvision torchaudio --index-url https://download.pytorch.org/whl/nightly/rocm6.2

# Alternative: Install stable PyTorch with ROCm support
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/rocm6.1

# Verify PyTorch installation
python -c "import torch; print(f'PyTorch version: {torch.__version__}')"
python -c "import torch; print(f'ROCm available: {torch.cuda.is_available()}')"
python -c "import torch; print(f'GPU device: {torch.cuda.get_device_name(0) if torch.cuda.is_available() else \"No GPU\"}')"

Step 3: Install Triton from Source

# First, uninstall any existing PyTorch-bundled Triton
pip uninstall -y pytorch-triton triton || true

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

# Verify Triton installation
python -c "import triton; print(f'Triton version: {triton.__version__}')"
python -c "import triton; print(f'Triton path: {triton.__file__}')"

Step 4: Install TritonParse

# Go back to tritonparse directory
cd ../tritonparse

# Install in development mode
pip install -e .

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

Step 5: 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 6: 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: Basic User Installation first to install PyTorch, Triton, and TritonParse.

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: Basic User Installation first to install PyTorch, Triton, and TritonParse.

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)

If you also need to work on the web interface, follow Option 2: Website Development Setup for additional setup.

🐛 Troubleshooting

Common Issues

1. Triton Installation Issues

# Error: "No module named 'triton'"
# Solution: Uninstall existing Triton and install from source
pip uninstall -y pytorch-triton triton || true
git clone https://github.com/triton-lang/triton.git
cd triton
pip install -e .

2. GPU Not Available

# Error: "CUDA not available" or "ROCm not available"
# Check GPU installation
python -c "import torch; print(f'GPU available: {torch.cuda.is_available()}')"
python -c "import torch; print(f'Device count: {torch.cuda.device_count()}')"

# For NVIDIA GPUs - Install CUDA-enabled PyTorch
pip install --pre torch torchvision torchaudio --index-url https://download.pytorch.org/whl/nightly/cu128
# Alternative: stable version
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118

# For AMD GPUs - Install ROCm-enabled PyTorch
pip install --pre torch torchvision torchaudio --index-url https://download.pytorch.org/whl/nightly/rocm6.2
# Alternative: stable version
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/rocm6.1

# Verify GPU support after installation
python -c "import torch; print(f'GPU available: {torch.cuda.is_available()}')"
python -c "import torch; print(f'GPU device: {torch.cuda.get_device_name(0) if torch.cuda.is_available() else \"No GPU\"}')"
python -c "import torch; print(f'Backend version: {torch.version.cuda if torch.version.cuda else torch.version.hip}')"

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:

# TritonParse specific
export TRITONPARSE_DEBUG=1                    # Enable debug logging
export TRITONPARSE_NDJSON=1                  # Enable NDJSON output (default)
export TRITON_TRACE_GZIP=1                   # Enable gzip compression
export TRITON_TRACE=/path/to/traces          # Custom trace directory

# PyTorch/TorchInductor related
export TORCHINDUCTOR_FX_GRAPH_CACHE=0        # Disable FX graph cache (for testing)
export TORCH_LOGS="+dynamo,+inductor"        # Enable PyTorch debug logs
export CUDA_VISIBLE_DEVICES=0                # Limit to specific NVIDIA GPU
export ROCR_VISIBLE_DEVICES=0                # Limit to specific AMD GPU (ROCm)
export HIP_VISIBLE_DEVICES=0                 # Alternative for AMD GPUs

# GPU debugging (if needed)
export CUDA_LAUNCH_BLOCKING=1                # Synchronous CUDA execution (NVIDIA)
export HIP_LAUNCH_BLOCKING=1                 # Synchronous HIP execution (AMD)
export TORCH_USE_CUDA_DSA=1                  # Enable CUDA device-side assertions (NVIDIA)

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

# Test PyTorch installation
import torch
print(f"PyTorch version: {torch.__version__}")
print(f"GPU available: {torch.cuda.is_available()}")
print(f"GPU device count: {torch.cuda.device_count()}")
if torch.cuda.is_available():
    print(f"GPU device: {torch.cuda.get_device_name(0)}")
    print(f"Backend version: {torch.version.cuda if torch.version.cuda else torch.version.hip}")

# Test Triton installation
import triton
print(f"Triton version: {triton.__version__}")

# Test TritonParse installation
import tritonparse.structured_logging
import tritonparse.utils
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