Modern Setup with tt-installer 2.0

Welcome to the fastest way to get started with Tenstorrent!

tt-installer 2.0 is Tenstorrent's official one-command installation tool that sets up your entire development environment in minutes. It replaces manual installation with an automated, production-tested approach.

What is tt-installer 2.0?

tt-installer 2.0 is a comprehensive installation script that:

• ✅ Installs the full Tenstorrent stack - Everything you need in one command
• ✅ Uses modern containers - tt-metalium runs in Podman containers (no complex builds)
• ✅ Configures your system - Kernel drivers, HugePages, firmware automatically set up
• ✅ Provides production tools - tt-smi, tt-flash, tt-inference-server included
• ✅ Supports multiple hardware - Works with N150, N300, T3K, Galaxy, P100, P150, P300c, and QB2
• ✅ Offers flexibility - Interactive or non-interactive modes, customizable options

⚠️ IMPORTANT: Cloud and Container Environments

If you're running in a cloud VM, Kubernetes, Docker, or any containerized environment:

• Use --mode-container flag or explicitly skip firmware/KMD updates
• DO NOT attempt to update firmware or kernel drivers unless you have full system control
• Host-level changes (KMD, HugePages, firmware) must be done on bare metal or with explicit cloud provider support
• See Container Mode section below for detailed guidance

Rule of thumb: If you're SSH'd into a cloud instance or running inside a container, use --mode-container or --no-install-kmd --no-update-firmware flags.

Why Use tt-installer Instead of Manual Setup?

Traditional approach (manual):

• Install system packages individually
• Clone and build tt-metal from source (20+ minutes)
• Configure Python environments manually
• Install kernel drivers with DKMS
• Set up HugePages in /etc/sysctl.conf
• Update firmware with tt-flash
• Install tt-smi separately
• Debug dependency issues
• Total time: 1-2 hours (if everything goes right)

Modern approach (tt-installer 2.0):

• Run one command
• Answer a few prompts
• Get coffee
• Total time: 5-15 minutes

What Gets Installed

tt-installer 2.0 sets up:

1. System packages - Build tools, dependencies (via apt/yum)

2. Python environment - Virtual environment with pip/pipx

3. Kernel-Mode Driver (KMD) - Tenstorrent hardware driver

4. Firmware updater (tt-flash) - Updates your card's firmware to latest

5. HugePages - Kernel memory configuration for fast hardware access

6. System Management Interface (tt-smi) - Monitor your Tenstorrent devices

7. Podman - Container runtime for tt-metalium

8. tt-metalium containers - Two options:

   • Standard container (1GB) - For TT-NN inference and development
   • Model Demos container (10GB) - Includes full tt-metal build and demos

9. tt-inference-server - Production inference serving

10. SFPI - Scalar Floating Point Interface for kernel development

Quick Start: One-Command Installation

The fastest way to get started:

/bin/bash -c "$(curl -fsSL https://github.com/tenstorrent/tt-installer/releases/latest/download/install.sh)"

What happens:

1. Downloads the latest installer script
2. Prompts you to choose Python environment strategy
3. Asks if you want the Model Demos container (10GB) or just standard (1GB)
4. Installs everything automatically
5. May ask to reboot (required for kernel driver)

Safety note: Always review scripts before running them. You can inspect the installer at: https://github.com/tenstorrent/tt-installer/releases/latest/download/install.sh

🚀 Run Quick Install

Step 1: Download and Inspect the Installer

For more control, download the installer first:

cd ~
curl -fsSL https://github.com/tenstorrent/tt-installer/releases/latest/download/install.sh -O
chmod +x install.sh

Then review it:

less install.sh

cd ~ && curl -fsSL https://github.com/tenstorrent/tt-installer/releases/latest/download/install.sh -O && chmod +x install.sh

Step 2: Run Interactive Installation

Run the installer with prompts to customize your setup:

cd ~
./install.sh

You'll be asked:

• Python environment choice - Use active venv, create new venv, use system Python, or use pipx
• Model Demos container - Install 10GB container with full tt-metal build? (yes/no)
• Reboot - Reboot now, later, or never (reboot required for kernel driver)

Recommended choices for most users:

• Python: new-venv (creates ~/.tenstorrent-venv)
• Model Demos: no (can install later if needed)
• Reboot: yes (required for kernel driver to load)

cd ~ && ./install.sh

Step 3: Non-Interactive Installation (Optional)

For automated deployments or cloud environments, use non-interactive mode:

./install.sh --mode-non-interactive \
  --python-choice=new-venv \
  --install-metalium-models-container=off \
  --reboot-option=never

Key flags:

• --mode-non-interactive - No prompts, uses defaults or provided flags
• --python-choice - Options: active-venv, new-venv, system-python, pipx
• --install-metalium-models-container=on/off - Install 10GB container with demos
• --reboot-option - Options: ask, never, always
• --no-install-kmd - Skip kernel driver (useful in containers)
• --no-install-hugepages - Skip HugePages config
• --metalium-image-tag=latest-rc - Pin specific container version

cd ~ && ./install.sh --mode-non-interactive --python-choice=new-venv --install-metalium-models-container=off --reboot-option=never

Step 4: Verify Installation

After installation (and reboot if prompted), verify everything works:

Check Hardware Detection

tt-smi

You should see your Tenstorrent device(s) listed with:

• Board Type (N150, N300, T3K, etc.)
• PCI Bus ID
• Firmware version
• Temperature
• Power draw

tt-smi

Test tt-metalium Container

Run a simple test inside the container:

tt-metalium "python3 -c 'import ttnn; print(ttnn.__version__)'"

This verifies:

• ✅ Container launches successfully
• ✅ TTNN library is available
• ✅ Python environment is configured

tt-metalium "python3 -c \

Using tt-metalium Containers

tt-installer provides two ways to use tt-metalium:

Interactive Shell

Launch an interactive session:

tt-metalium

This:

• Starts a bash shell inside the container
• Mounts your home directory (access your files)
• Provides full tt-metal environment
• Use exit to leave the container

Run Commands Directly

Execute commands without entering the shell:

# Check TTNN version
tt-metalium "python3 -c 'import ttnn; print(ttnn.__version__)'"

# Run a Python script
tt-metalium "python3 ~/my-inference-script.py"

# Use pytest (for demos)
tt-metalium "pytest models/demos/wormhole/llama31_8b/demo/demo.py"

Key benefit: Your files in ~ are automatically accessible inside the container!

Standard vs Model Demos Container

Standard container (1GB) - tt-metalium:

• ✅ TTNN library for inference
• ✅ Python 3.10+ environment
• ✅ Fast to download and update
• ✅ Best for production inference
• ❌ No model demos included
• ❌ No tt-metal source code

Model Demos container (10GB) - tt-metalium-models:

• ✅ Full tt-metal repository with demos
• ✅ Pre-compiled examples
• ✅ All model demos (LLMs, vision, audio)
• ✅ Source code for learning
• ❌ Large download (10GB)
• ❌ Slower to update

Recommendation:

• Start with standard container (1GB)
• Install Model Demos later if you want to explore examples
• You can have both installed simultaneously

Advanced Options

Pin Specific Versions

Install specific versions of components:

./install.sh \
  --kmd-version=1.34 \
  --fw-version=80.18.3.0 \
  --smi-version=2.0.0 \
  --metalium-image-tag=v0.53.0-rc36

Skip Components

Customize what gets installed:

./install.sh \
  --no-install-kmd \              # Skip kernel driver (for containers)
  --no-install-hugepages \        # Skip HugePages config
  --no-install-podman \           # Skip Podman (if you have Docker)
  --no-install-metalium-container # Skip container download

Container Mode

When running inside a container (like Docker) or cloud environment, use container mode:

./install.sh --mode-container

This automatically:

• Skips KMD installation (must be on host)
• Skips HugePages configuration (must be on host)
• Skips Podman installation (no nested containers)
• Skips firmware updates (requires host access)
• Never attempts reboot

Cloud Environment Best Practices

When running in cloud VMs (AWS, GCP, Azure, etc.):

1. Bare Metal Instances Only: Tenstorrent hardware requires PCIe passthrough - only works on bare metal instances, not virtualized VMs
2. Provider-Managed Drivers: If your cloud provider pre-installs KMD and firmware, use:

   ./install.sh --no-install-kmd --no-update-firmware --no-install-hugepages
   

3. Container Orchestration (Kubernetes): For pods running tt-metalium:

   ./install.sh --mode-container
   

   • KMD must be installed on host nodes
   • HugePages configured via Kubernetes DaemonSet
   • Firmware managed by cluster admins

When NOT to tamper with firmware/KMD:

• ❌ Inside Docker/Podman containers
• ❌ Kubernetes pods without privileged access
• ❌ Cloud instances where provider manages hardware
• ❌ Shared infrastructure where you're not the admin
• ❌ Any environment where you can't reboot the host

Safe operations in restricted environments:

• ✅ Installing Python packages (tt-smi, tt-inference-server)
• ✅ Running tt-metalium containers (if host has KMD)
• ✅ Using tt-smi to monitor devices
• ✅ Running inference workloads

Custom Python Environment

Specify where to create the Python venv:

./install.sh \
  --python-choice=new-venv \
  --new-venv-location=$HOME/my-custom-venv

Custom Container Image

Use a different container image or registry:

./install.sh \
  --metalium-image-url=myregistry.example.com/tt-metalium \
  --metalium-image-tag=custom-build-123

Use UV Instead of Pip

For faster Python package installation:

./install.sh --use-uv=on

uv is a faster alternative to pip written in Rust.

Post-Installation: Next Steps

After installation completes, you're ready to:

1. Explore Lessons 3-12 - This walkthrough teaches you how to:

   • Download and run LLMs (Lesson 3)
   • Build chat interfaces (Lessons 4-5)
   • Deploy production vLLM servers (Lessons 6-7)
   • Generate images with Stable Diffusion (Lesson 8)
   • Create coding assistants (Lesson 9)
   • Use TT-Jukebox for model management (Lesson 10)
   • Compile models with tt-forge-fe" target="_blank" rel="noreferrer">TT-Forge (Lesson 11)
   • Use JAX with TT-XLA (Lesson 12)

2. Try Model Demos (if you installed Model Demos container):

   tt-metalium-models
   cd tt-metal/models/demos
   pytest wormhole/llama31_8b/demo/demo.py
   

3. **Read Official Documentation**:
   - [TT-Metalium Docs](https://docs.tenstorrent.com/tt-metal/latest/)
   - [TTNN Examples](https://docs.tenstorrent.com/tt-metal/latest/ttnn/ttnn/usage.html)
   - [tt-installer Wiki](https://github.com/tenstorrent/tt-installer/wiki)

4. **Join the Community**:
   - [Discord](https://discord.gg/tenstorrent)
   - [GitHub Discussions](https://github.com/tenstorrent/tt-metal/discussions)

## Troubleshooting

### Installation fails with "Permission denied"

**Problem:** Installer requires sudo permissions.

**Solution:** Run with sudo or ensure your user is in sudoers file:
```bash
sudo ./install.sh

"tt-smi: command not found" after installation

Problem: Python environment not activated or PATH not updated.

Solution:

# If using pipx (default)
pipx ensurepath
source ~/.bashrc

# If using venv
source ~/.tenstorrent-venv/bin/activate

Kernel driver not loading

Problem: Reboot required after KMD installation.

Solution:

sudo reboot
# After reboot, verify:
lsmod | grep tenstorrent

Container fails to start

Problem: Podman not configured or device permissions issue.

Solution:

# Check Podman status
podman info

# Check device permissions
ls -l /dev/tenstorrent/

# Re-run installer to fix permissions
./install.sh --no-install-kmd --no-install-hugepages

Firmware update fails

Problem: Device not detected or firmware file corrupted.

Solution:

# Verify device detection first
tt-smi

# Force firmware update
./install.sh --update-firmware=force --no-install-kmd

HugePages not configured

Problem: Installation skipped HugePages or reboot didn't apply changes.

Solution:

# Check current HugePages
cat /proc/meminfo | grep Huge

# Re-run installer to configure
./install.sh --no-install-kmd --no-install-podman

# Then reboot
sudo reboot

Model Demos container too large

Problem: 10GB download too slow or disk space limited.

Solution: Use standard container only:

./install.sh --install-metalium-models-container=off

You can always add it later:

./install.sh --no-install-kmd --no-install-hugepages --install-metalium-models-container=on

Supported Operating Systems

Recommended: Ubuntu 22.04.5 LTS for best compatibility.

Comparison: tt-installer vs Manual Setup

When to Use Manual Setup Instead

tt-installer is recommended for most users, but manual setup may be preferred if:

• ❌ You need bleeding-edge unreleased features (build from main branch)
• ❌ You're developing tt-metal itself (need source code access)
• ❌ Your OS is unsupported by tt-installer
• ❌ You need custom compiler flags or build options
• ❌ You're debugging kernel driver issues (need to build KMD yourself)

For 95% of users, tt-installer is the right choice.

Frequently Asked Questions

Q: Can I use tt-installer inside a Docker container?

A: Yes, but use --mode-container flag:

./install.sh --mode-container

This skips host-level changes (KMD, firmware, HugePages) that must be done on the host system. The container can still run tt-metalium and use devices if the host has proper drivers installed.

Q: I'm running in AWS/GCP/Azure - should I update firmware?

A: No, not unless you're on a bare metal instance and have full control. Cloud providers may manage firmware and drivers for you. Use:

./install.sh --no-install-kmd --no-update-firmware

Check with your cloud provider's documentation for Tenstorrent support.

Q: What's the difference between --mode-container and --no-install-kmd?

A:

• --mode-container - Skips ALL host-level changes (KMD, firmware, HugePages, reboot). Use inside Docker/Kubernetes.
• --no-install-kmd - Skips only KMD installation. Use when KMD is already installed or managed elsewhere.

You can combine flags for fine-grained control:

./install.sh --no-install-kmd --no-update-firmware --no-install-hugepages

Q: Can I run tt-metalium without KMD installed?

A: No. The Tenstorrent kernel driver must be installed on the host system for hardware access. Containers can use devices if the host has KMD loaded.

Q: How do I know if I'm in a restricted environment?

A: If any of these are true, you're likely restricted:

• You can't run sudo reboot without approval
• You're inside a Docker/Podman container (/.dockerenv file exists)
• You're in a Kubernetes pod (/var/run/secrets/kubernetes.io exists)
• You don't have sudo access
• Cloud provider manages your instance's kernel/firmware

Use --mode-container or skip flags in these cases.

Q: What if firmware update fails in my cloud environment?

A: Firmware updates require direct hardware access and may not work in cloud environments. Options:

1. Skip firmware updates: ./install.sh --no-update-firmware
2. Use cloud provider's firmware (if pre-installed)
3. Contact cloud provider support for Tenstorrent firmware management
4. If on bare metal with full control, ensure proper PCIe access

Q: Can I use tt-installer in Kubernetes?

A: Yes, with proper setup:

• Install KMD and firmware on host nodes (outside containers)
• Configure HugePages on host nodes
• Inside pods, use: ./install.sh --mode-container
• Mount /dev/tenstorrent devices into pods
• Use privileged security context if needed

See Using tt-metalium Container for Kubernetes examples.

Resources

Official Documentation:

• tt-installer GitHub
• tt-installer Wiki
• Customizing Installation
• Using tt-metalium Container

Community:

• Discord
• GitHub Issues

Next Steps:

• Continue to Lesson 1: Hardware Detection (verify installation)
• Skip to Lesson 3: Download Model (start running inference)
• Explore Lessons 6-7: Production vLLM deployment

Congratulations! You now have a complete Tenstorrent development environment.

The next lessons will teach you how to use this environment to run inference, build applications, and deploy production services.