Install
These instructions will guide you through the installation of Tenstorrent system tools and drivers, followed by the installation of TT-Metalium and TT-NN.
[!IMPORTANT]
If you are using a release version of this software, check installation instructions packaged with it. You can find them in either the release assets for that version, or in the source files for that version tag.
Prerequisites:
1: Set Up the Hardware
Follow the instructions for the Tenstorrent device you are using at: Hardware Setup
2: Install Driver & Firmware
Note the current compatibility matrix:
Device |
OS |
Python |
Driver (TT-KMD) |
Firmware (TT-Flash) |
TT-SMI |
TT-Topology |
---|---|---|---|---|---|---|
Wormhole |
Ubuntu 22.04 |
3.8.10 |
v1.29 |
fw_pack-80.13.0.0 (v80.13.0.0) |
v2.2.0 or above |
N/A |
T3000 (Wormhole) |
Ubuntu 22.04 |
3.8.10 |
v1.29 |
fw_pack-80.13.0.0 (v80.13.0.0) |
v2.2.0 or above |
v1.1.3 or above, |
Blackhole |
Ubuntu 22.04 |
3.10 |
v1.31 |
fw_pack-80.15.0.0 (v80.15.0.0) |
v3.0.5 or above |
v1.1.3 or above, ‘mesh’ config |
Install System-level Dependencies
wget https://raw.githubusercontent.com/tenstorrent/tt-metal/refs/heads/main/install_dependencies.sh
chmod a+x install_dependencies.sh
sudo ./install_dependencies.sh
Install the Driver (TT-KMD)
DKMS must be installed:
OS |
Command |
---|---|
Ubuntu / Debian |
|
Fedora |
|
Enterprise Linux Based |
|
Install the latest TT-KMD version:
git clone https://github.com/tenstorrent/tt-kmd.git
cd tt-kmd
sudo dkms add .
sudo dkms install "tenstorrent/$(./tools/current-version)"
sudo modprobe tenstorrent
cd ..
For more information visit Tenstorrents TT-KMD GitHub repository.
Update Device TT-Firmware with TT-Flash
Install TT-Flash:
pip install git+https://github.com/tenstorrent/tt-flash.git
Reboot to load changes:
sudo reboot
Check if TT-Flash is installed:
tt-flash --version
Download and install the latest TT-Firmware version:
file_name=$(curl -s "https://raw.githubusercontent.com/tenstorrent/tt-firmware/main/latest.fwbundle")
curl -L -o "$file_name" "https://github.com/tenstorrent/tt-firmware/raw/main/$file_name"
tt-flash flash --fw-tar $file_name
For more information visit Tenstorrent’s TT-Firmware GitHub Repository and TT-Flash Github Repository.
Install System Management Interface (TT-SMI)
Install Tenstorrent Software Management Interface (TT-SMI):
pip install git+https://github.com/tenstorrent/tt-smi
Verify System Configuration
Once hardware and system software are installed, verify that the system has been configured correctly.
Run the TT-SMI utility:
tt-smi
A display with device information, telemetry, and firmware will appear:
If the tool runs without error, your system has been configured correctly.
For more information, visit Tenstorrent’s TT-SMI GitHub repository.
(Optional) Multi-Card Configuration (TT-Topology)
For TT-Loudbox or TT-QuietBox systems, visit Tenstorrent’s TT-Topology README.
TT-NN / TT-Metalium Installation
There are three options for installing TT-Metalium:
-
Installing from source gets developers closer to the metal and the source code.
-
Option 2: From Docker Release Image
Installing from Docker Release Image is the quickest way to access our APIs and to start running AI models.
-
Install from wheel as an alternative method to get quick access to our APIs and to running AI models.
Option 1: From Source
Install from source if you are a developer who wants to be close to the metal and the source code. Recommended for running the demo models.
Step 1. Clone the Repository:
git clone https://github.com/tenstorrent/tt-metal.git --recurse-submodules
Step 2. Invoke our Build Scripts:
./build_metal.sh
(recommended) For an out-of-the-box virtual environment to use, execute:
./create_venv.sh
source python_env/bin/activate
-
(optional) Software dependencies for profiling use:
Install dependencies:
sudo apt install pandoc libtbb-dev libcapstone-dev pkg-config
Download and install Doxygen, (v1.9 or higher, but less than v1.10)
Continue to You Are All Set!
Option 2: From Docker Release Image
Installing from Docker Release Image is the quickest way to access our APIs and to start running AI models.
Download the latest Docker release from our Docker registry page
docker pull ghcr.io/tenstorrent/tt-metal/tt-metalium-ubuntu-22.04-amd64-release:latest-rc
docker run -it --rm -v /dev/hugepages-1G:/dev/hugepages-1G --device /dev/tenstorrent ghcr.io/tenstorrent/tt-metal/tt-metalium-ubuntu-22.04-amd64-release:latest-rc bash
For more information on the Docker Release Images, visit our Docker registry page.
Continue to You Are All Set!
Option 3: From Wheel
Install from wheel for quick access to our APIs and to get an AI model running
Step 1. Download and Install the Latest Wheel:
Navigate to our releases page and download the latest wheel file for the Tenstorrent card architecture you have installed.
-
Install the wheel using your Python environment manager of choice. For example, to install with
pip
:pip install <wheel_file.whl>
Step 2. (For models users only) Set Up Environment for Models:
To try our pre-built models in models/
, you must:
Install their required dependencies
Set appropriate environment variables
Set the CPU performance governor to ensure high performance on the host
-
This is done by executing the following:
export PYTHONPATH=$(pwd) pip install -r tt_metal/python_env/requirements-dev.txt sudo apt-get install cpufrequtils sudo cpupower frequency-set -g performance
You are All Set!
To verify your installation, try executing a programming example:
-
First, set the following environment variables:
Run the appropriate command for the Tenstorrent card you have installed:
Card
Command
Grayskull
export ARCH_NAME=grayskull
Wormhole
export ARCH_NAME=wormhole_b0
Blackhole
export ARCH_NAME=blackhole
Run:
export TT_METAL_HOME=$(pwd) export PYTHONPATH=$(pwd)
-
Then, try running a programming example:
python3 -m ttnn.examples.usage.run_op_on_device
For more programming examples to try, visit Tenstorrent’s TT-NN Basic Examples Page or get started with Simple Kernels on TT-Metalium
Interested in Contributing?
For more information on development and contributing, visit Tenstorrent’s CONTRIBUTING.md page.