Verify Your Setup

This is your diagnostic checkpoint. Run three quick checks to confirm hardware, TT-NN^™, and (optionally) tt-metal source are ready. If anything fails, follow the link for that check — then come back here to confirm you're green before moving on.

TT-QuietBox^® 2 / Pre-configured image users: TT-QuietBox 2 ships with a pre-installed environment but does not include ~/tt-metal. Check 1 passes on the host out of the box. Check 2 does not — ~/.tenstorrent-venv holds only the hardware tooling (tt-smi, tt-flash, tt-topology), not TT-NN^™ or vLLM, so a bare host import ttnn fails with ModuleNotFoundError. Run Check 2 inside the tt-metalium container instead (see the QB2 note under Check 2 below). Check 3 will fail unless you clone and build TT-Metalium^™ yourself — that's expected and fine for most lessons.

Which path are you on?

Before running checks, pick the path that matches your goal:

Not sure? Start with the vLLM path — it works on all hardware without needing to build from source.

Check 1: Hardware

Run this in your terminal:

tt-smi -s

tt-smi

Interpreting results:

• JSON output shows your device(s) → ✅ Hardware OK, continue to Check 2
• command not found → drivers or tt-smi not installed → go to TT-Installer and return here when done
• Device shown but with error flags → firmware or driver issue; consult TT-Installer troubleshooting

Check 2: TT-NN

python3 -c "import ttnn; print('✓ TTNN', getattr(ttnn, '__version__', '(source build)'))"

On a TT-QuietBox 2: the command above will fail on the bare host — ~/.tenstorrent-venv doesn't contain TT-NN. Run it inside the tt-metalium container instead:

tt-metalium -c "python3 -c \"import ttnn; print('✓ TTNN', getattr(ttnn, '__version__', '(source build)'))\""

Interpreting results:

• Prints ✓ TT-NN <version> → ✅ TT-NN ready, continue to Check 3
• ModuleNotFoundError: No module named 'ttnn' → TT-NN is not importable in your current Python environment. You need one of:
  • TT-QuietBox 2 / TT-Installer users: run the check inside the tt-metalium container (see above) — ~/.tenstorrent-venv is hardware tooling only, not a TT-NN environment
  • Build-from-source users: activate your tt-metal venv and set TT_METAL_HOME:

    source ~/tt-metal/python_env_3.12/bin/activate   # or python_env for Python 3.10
    export TT_METAL_HOME=~/tt-metal
    export PYTHONPATH=$TT_METAL_HOME:$PYTHONPATH
    

  • Don't have TT-Metalium yet: go to Build TT-Metalium from Source and return here when done
• ImportError: undefined symbol: MPIX_Comm_revoke → OpenMPI libraries missing from LD_LIBRARY_PATH:

  export LD_LIBRARY_PATH=/opt/openmpi-v5.0.7-ulfm/lib:$LD_LIBRARY_PATH
  

Check 3: tt-metal source (optional)

Skip this check if you are using the vLLM production path — tt-metal source is not required. Only the Generator API lessons (Interactive Chat) need it.

[ -d ~/tt-metal ] && echo "✓ tt-metal source present at ~/tt-metal" \
  || echo "✗ ~/tt-metal not found — OK for vLLM path, needed for Generator API"

Interpreting results:

• ✓ tt-metal source present → ✅ Source ready. Generator API lessons will work. If TT-Metalium is present but not yet built, run bash /tmp/build_tt_metal.sh inside the developer container, or go to Build TT-Metalium from Source.
• ✗ ~/tt-metal not found → Source not present. That's expected on TT-QuietBox 2 pre-installed images and fine for all vLLM production lessons. Only needed for the Generator API (Interactive Chat). If you need it, go to Build TT-Metalium from Source and return here when done.

All checks green?

Choose your next step based on your goal:

• vLLM production serving (Qwen3-0.6B, no source needed) → vLLM Production →
• Interactive chat (requires tt-metal source + Llama model) → Interactive Chat →
• Still something failing? → Build TT-Metalium from Source →