01. Installation

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

📋 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+
  • AMD GPUs: ROCm 5.0+ (supports MI100, MI200, MI300 series)
• Node.js >= 22.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.

---

🔧 Install Required Dependencies

All installation options require PyTorch and Triton. Complete these steps first before choosing your installation option below.

Step 1: 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

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

Step 2: Verify GPU Setup

# Verify PyTorch and GPU
python -c "import torch; print(f'PyTorch: {torch.__version__}')"
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\"}')"

# Verify Triton (bundled with PyTorch)
python -c "import triton; print(f'Triton: {triton.__version__}')"

💡 Note: Triton is bundled with PyTorch nightly and recent stable releases. No separate installation is needed.

---

🎯 Installation Options

Now choose your installation method based on your needs:

Option 1: PyPI Installation (Recommended for Most Users)

Quick installation from Python Package Index

# Install nightly version (recommended, latest features)
pip install -U --pre tritonparse

# OR install stable version
pip install tritonparse

Option 2: Install from Source

# Clone and install
git clone https://github.com/meta-pytorch/tritonparse.git
cd tritonparse
pip install -e .

# OR install directly from GitHub without cloning
pip install git+https://github.com/meta-pytorch/tritonparse.git

Additional setup for contributors:

# For Python development: install formatting tools (black, usort, ruff)
make install-dev

# For website development: install Node.js dependencies (requires Node.js >= 22.0.0)
cd website && npm install
npm run dev  # Start dev server at http://localhost:5173

---

✅ Verify Installation

Test that TritonParse is working correctly:

# Navigate to tests directory
cd tests  # or cd tritonparse/tests if you didn't clone

# Run example test
TORCHINDUCTOR_FX_GRAPH_CACHE=0 python test_add.py

Expected output:

Triton kernel executed successfully
Torch compiled function executed successfully
================================================================================
📁 TRITONPARSE PARSING RESULTS
================================================================================
📂 Parsed files directory: /scratch/findhao/tritonparse/tests/parsed_output
📊 Total files generated: 2
...
✅ Parsing completed successfully!
================================================================================

Using the Web Interface

1. Generate trace files using the Python API (see Usage Guide)
2. Visit https://meta-pytorch.org/tritonparse/
3. Load your trace files (.ndjson or .gz format)

Additional Commands for Development

For Python development (Option 3):

# Check code formatting
make format-check

# Run linting
make lint-check

# Run tests
make test

For website development (Option 4):

npm run dev          # Development server
npm run build        # Production build
npm run build:single # Standalone HTML build
npm run preview      # Preview production build

---

🐛 Troubleshooting

Common Issues

1. GPU Not Available

Error: "CUDA not available" or "ROCm not available"

Diagnosis:

python -c "import torch; print(f'GPU available: {torch.cuda.is_available()}')"
python -c "import torch; print(f'Device count: {torch.cuda.device_count()}')"

Solution: Reinstall PyTorch with GPU support following Step 1 above.

2. Triton Installation Issues

Error: "No module named 'triton'" or "Triton version mismatch"

Solution:

pip uninstall -y pytorch-triton triton || true
pip install --upgrade triton

3. Permission Issues

Error: Permission denied during installation

Solution: Use a virtual environment

python -m venv tritonparse-env
source tritonparse-env/bin/activate  # Linux/Mac
# OR
tritonparse-env\Scripts\activate  # Windows

4. Development Tools Not Found

Error: "black not found" or similar

Solution:

make install-dev
# OR manually: pip install black usort ruff

5. Website Build Issues

Error: Node.js version too old

Solution:

# Update Node.js to >= 22.0.0
conda install 'nodejs>=22.0.0' -c conda-forge

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

Useful Environment Variables

💡 See Environment Variables Reference for complete documentation of all variables.

# TritonParse
export TRITONPARSE_DEBUG=1                   # Enable debug logging
export TRITON_TRACE_COMPRESSION=gzip          # Enable gzip compression
export TRITON_TRACE=/path/to/traces          # Custom trace directory
export TRITON_TRACE_LAUNCH=1                 # Enable launch tracing
export TRITONPARSE_MORE_TENSOR_INFORMATION=1 # Collect tensor statistics

# PyTorch/TorchInductor
export TORCHINDUCTOR_FX_GRAPH_CACHE=0        # Disable FX graph cache (for testing)
export TORCH_LOGS="+dynamo,+inductor"        # Enable PyTorch debug logs

# GPU control
export CUDA_VISIBLE_DEVICES=0                # Limit to specific GPU (NVIDIA)
export ROCR_VISIBLE_DEVICES=0                # Limit to specific GPU (AMD)
export CUDA_LAUNCH_BLOCKING=1                # Synchronous CUDA execution (for debugging)

Getting Help

If you encounter issues:

1. Check the Troubleshooting section above
2. Review the FAQ for frequently asked questions
3. Search GitHub Issues
4. Open a new issue with system info (python --version, pip list) and error messages

---

🚀 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. Review the Environment Variables Reference for configuration options
5. See the Python API Reference for complete API documentation
6. Join the GitHub Discussions for community support