Installing the Stack

On a QB2 from Tenstorrent, this is already done. The venvs are there, the driver is loaded, the firmware is flashed. This chapter is for understanding what exists and where — so you know which environment to activate when, and what to do if something’s missing.

Installing the Tenstorrent Software Stack

On a QB2 from Tenstorrent, the stack is already there. This section is for installing on a fresh Ubuntu system, or understanding what the installer put where.

Prerequisites: Ubuntu 24.04 LTS (or 22.04), internet connection, sudo access.

sudo apt update && sudo apt install -y curl jq
curl -fsSL https://github.com/tenstorrent/tt-installer/releases/latest/download/install.sh | /bin/bash -s -- --use-uv

The installer handles drivers, firmware, kernel modules, and all three Python environments. Accept the defaults — they’re right for a QB2.

--use-uv tells the installer to build its Python environment with uv instead of python3 -m venv + pip, which sidesteps the usual host-Python headaches — no ensurepip, no distro Python that’s the wrong version, no --break-system-packages. It’s the “just works” path Tenstorrent is moving toward — tenstorrent.github.io#200 adds it to the official QB2 setup doc, which today still runs the installer without it. Nothing else changes: the venv still lands at ~/.tenstorrent-venv, and the installer fetches uv into ~/.local/bin/ if you don’t already have it. The flag is available in current releases (v2.1.0+) and is what makes --python-version 3.12 work if you ever need to pin an interpreter.

Note the <(…) process substitution rather than -c "$(…)" — with bash -c, a trailing flag becomes $0 and the installer never sees it. If you want a hands-off run, add --mode-non-interactive.

After it finishes, reboot:

sudo reboot

What ends up on your QB2

As of tt-installer v3.2.0, Docker is the default container runtime (Podman is still supported — pass --install-container-runtime=podman). The Metalium container installs by default. Forge is not installed by default — the TT-Forge docs install it as a pip wheel (pip install pjrt-plugin-tt … then tt-forge-install); tt-installer’s --install-forge-container is an optional convenience, not the recommended path. See the TT-Forge chapter for the full install. On a QB2 that shipped from Tenstorrent, the TTNN venv at ~/tt-metal/python_env/ is pre-built. The ~/tt-metal/ directory contains compiled environments — not the tt-metal source code.

What You Have

On a QB2 from Tenstorrent, the stack is pre-installed. Here’s your map:

Create the scratch directory if it doesn’t exist yet:

mkdir -p ~/tt-scratchpad ~/models

The Three Environments, Explained

TTNN (~/tt-metal/python_env/)

This is the workhorse. Use it for direct Python API work — opening devices, running TTNN operations, the cookbook examples in this guide.

source ~/tt-metal/python_env/bin/activate
# prompt changes to (python_env)
python3 -c "import ttnn; print('TTNN ready')"
deactivate

vLLM (in ~/.tenstorrent-venv)

Use this to run a model as a server with an OpenAI-compatible HTTP API. vLLM is available in the main tenstorrent venv:

source ~/.tenstorrent-venv/bin/activate

export TT_METAL_ARCH_NAME=blackhole
export MESH_DEVICE=P300              # one P300 card; P300x2 uses all four chips
export VLLM_RPC_TIMEOUT=900000       # the 10s default is far too short for a first compile

# HF_MODEL must match the --model path. tt-metal's tt_transformers reads it as the
# checkpoint directory, so serving a local path without it fails outright.
export HF_MODEL=~/models/Llama-3.1-8B-Instruct

vllm serve ~/models/Llama-3.1-8B-Instruct --port 8000

Watch the startup log for a line saying the tt platform has been selected. Without it, vLLM is running but cannot see your hardware — see the vLLM on QB2 chapter.

Or use tt-studio for a no-code UI that handles vLLM startup automatically.

TT-Forge (tt-forge wrapper)

tt-forge is a Docker container wrapper installed to ~/.local/bin/ by tt-installer. It runs the TT-XLA/Forge compiler stack without requiring a local Python venv:

# Use the tt-forge wrapper directly
tt-forge --help

For scripting with import forge in Python, use the tt-forge-fe source tree or check docs.tenstorrent.com/tt-forge for current installation instructions.

Confirming Each Environment Works

Run this check sequence:

# TTNN
source ~/tt-metal/python_env/bin/activate
python3 -c "import ttnn; print('✓ TTNN')" && deactivate

# vLLM (in the main tenstorrent venv)
source ~/.tenstorrent-venv/bin/activate
python3 -c "import vllm; print('✓ vLLM')" && deactivate

# Check for the tt-smi binary
which tt-smi && tt-smi --version

All three should respond without errors. If TTNN import fails, the venv may not be set up — check docs.tenstorrent.com for the current setup guide. If tt-smi isn’t found, add ~/.local/bin to your PATH (see below).

Installing tt-smi if it’s Missing

On a QB2 it shouldn’t be missing, but on another Ubuntu system:

# Option A — public PyPI (any machine, no PPA needed):
pip install tt-smi

# Option B — via apt (requires Tenstorrent PPA, set up by tt-installer):
sudo apt install tt-smi

Both install the same tool. Option A works anywhere with Python; option B integrates with your system package manager. On a freshly installed Ubuntu machine without tt-installer, option A is the easier path.

Disk Space and Model Storage

Models consume significant disk space. Plan accordingly:

The convention across all Tenstorrent documentation is ~/models/<model-name>/. Nothing enforces this — you can store models anywhere and point --model at any path — but using the convention means every tutorial command works without substitution.

Check space before any download:

df -h ~/models

Next: Your First Model →