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
/bin/bash -c "$(curl -fsSL https://tenstorrent.ai/install.sh)"

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

After it finishes, reboot:

sudo reboot

The Tenstorrent apt repository (and its signing key)

Most of what the installer puts on the machine — the tenstorrent-dkms kernel driver, tt-smi, tt-flash, tt-topology, tt-toplike, tt-metalium, tt-nn, sfpi — comes from Tenstorrent’s own apt repository. Two things have to be in place for that: the repository line, and the key apt uses to verify it. Miss the key and apt refuses the repository outright.

tt-installer sets both up. These are the commands it runs, if you’d rather add the repository without the full installer, or need to repair it:

# 1. Keyring directory
sudo mkdir -p /etc/apt/keyrings
sudo chmod 755 /etc/apt/keyrings

# 2. The signing key — this is the step that gets skipped
sudo curl -fsSL -o /etc/apt/keyrings/tt-pkg-key.asc https://ppa.tenstorrent.com/tt-pkg-key.asc

# 3. The repository, pinned to that key
echo "deb [signed-by=/etc/apt/keyrings/tt-pkg-key.asc] https://ppa.tenstorrent.com/ubuntu/ $(. /etc/os-release && echo "$VERSION_CODENAME") main" \
  | sudo tee /etc/apt/sources.list.d/tenstorrent.list > /dev/null

# 4. Refresh
sudo apt-get update

On Debian, swap /ubuntu/ for /debian/. On Fedora, write /etc/yum.repos.d/tenstorrent.repo with gpgkey=https://ppa.tenstorrent.com/tt-pkg-key.asc — dnf fetches the key from the URL, so there’s no keyring file to manage.

Check it took:

# The key: a PGP block, non-zero size, readable by _apt (mode 644)
head -1 /etc/apt/keyrings/tt-pkg-key.asc
ls -l /etc/apt/keyrings/tt-pkg-key.asc

# The repository line, and where packages now resolve from
cat /etc/apt/sources.list.d/tenstorrent.list
apt-cache policy tt-smi

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 installs as a pip wheel into the main venv (~/.tenstorrent-venv/) unless you pass --forge-container, in which case a container image is pulled and the tt-forge wrapper script lands at ~/.local/bin/tt-forge.

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 the Tenstorrent repository, 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.

Option B needs the Tenstorrent repository and its signing key at /etc/apt/keyrings/tt-pkg-key.asc — see The Tenstorrent apt repository above. If apt complains the repository isn’t signed, that key is what’s missing.

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 →