Install

This document provides advanced users and developers with comprehensive instructions for installing Tenstorrent’s stack, featuring multiple deployment options for 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 Software Dependencies

Option 2: Manual Installation

TT-NN / TT-Metalium Installation

There are four options for installing TT-Metalium:

Binaries

Install from wheel for quick access to ttnn Python APIs and to get an AI model running. All binaries support only Linux and distros with glibc 2.34 or newer.

Step 1. Install the Latest Wheel:

  • Install the wheel using pip:

    pip install ttnn

Step 2. (For models users only) Set Up Environment for Models:

To try our pre-built models in tt-metal/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

Container-Based Setup

Container-based setup is recommended when you want a predictable user-space environment with minimal host-side package management.

Use this path when:

  • you want to evaluate the stack quickly,

  • you want to run demos in a known image,

  • you want to avoid debugging host Python dependency drift,

  • you prefer Docker or rootless Podman over modifying the host environment.

Use the source path instead when:

  • you are changing tt-metal source code,

  • you need editable local builds,

  • you are iterating on kernels, C++, or Python bindings,

  • you need direct control over build flags or toolchains.

Docker workflow 

docker pull ghcr.io/tenstorrent/tt-metal/tt-metalium-ubuntu-22.04-release-amd64:latest-rc
docker run -it --rm --device /dev/tenstorrent ghcr.io/tenstorrent/tt-metal/tt-metalium-ubuntu-22.04-release-amd64:latest-rc bash

Rootless Podman workflow

If your environment standardizes on rootless containers, use Podman with the same image:

podman pull ghcr.io/tenstorrent/tt-metal/tt-metalium-ubuntu-22.04-release-amd64:latest-rc
podman run -it --rm --device /dev/tenstorrent ghcr.io/tenstorrent/tt-metal/tt-metalium-ubuntu-22.04-release-amd64:latest-rc bash

[!NOTE] Device access requirements depend on your host configuration. If /dev/tenstorrent is not visible inside the container, confirm that the device node exists on the host and that your container runtime is configured to pass it through.

Verification steps

After entering the container:

  1. Confirm that the Tenstorrent device node is visible:

    ls /dev/tenstorrent

If you plan to run models or edit code from a local source checkout instead of staying inside the packaged container environment, continue with the source-based environment setup for model-specific dependencies and environment variables.

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. Build the Library:

You have two options for building the library:

Option A: Using the Build Script (Recommended)

The build script provides the simplest way to build the library and works well with the standard build tools installed via install_dependencies.sh.

./build_metal.sh

Option B: Manual Build with CMake

For users who prefer more control over build options or have custom setups, you can build manually:

mkdir build
cd build
cmake .. -G Ninja -DCMAKE_BUILD_TYPE=RelWithDebugInfo -DCMAKE_CXX_COMPILER=<your compiler>
ninja
ninja install # Installs to build directory by default, required for Python environment

Step 3. Virtual Environment Setup

  • (Optional) Specify existing python environment:

export PYTHON_ENV_DIR=<path_to_your_env_directory>

  • Run the script to set up your Python environment:

./create_venv.sh
source python_env/bin/activate

Note: If PYTHON_ENV_DIR is not set, the script creates a new virtual environment in ./python_env

Anaconda

Anaconda is another virtual environment manager. There is a community driven recipe here. There is support for Python 3.10, 3.11, and 3.12. All binaries support only Linux and distros with glibc 2.34 or newer.

Step 1. Install the Latest Package:

  • Install the package using conda:

    conda create -n metalium python=3.10 tt-metalium -c conda-forge

You are All Set!

To verify your installation (for source or wheel installation only), try executing a programming example:

  • First, set the following environment variables:

    export PYTHONPATH=</path/to/your/tt-metal>

  • 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?

Multi-Card Configuration (TT-Topology)

TT-Topology can be used to specify different eth routing configurations for some multi-card systems such as TT-Loudbox and TT-QuietBox.

Virtual Machine Requirements

[!IMPORTANT]

If you are running this software in a virtual machine, additional configuration is required.

Overview

This software requires an IOMMU (Input-Output Memory Management Unit) to be enabled at the host level to ensure proper memory isolation and device passthrough support. On virtual machines, this translates to enabling the virtual IOMMU (vIOMMU) feature in the hypervisor.

Why It Matters

  • Enables secure and efficient DMA operations

  • Required for PCIe passthrough to guest VMs (e.g., for hardware accelerators)

  • Prevents host memory corruption by restricting device access

Requirements for VMs

To run this software reliably in a VM:

  • The host machine must have IOMMU support enabled (e.g., intel_iommu=on or amd_iommu=on in kernel parameters)

  • The virtual machine must be provisioned with a vIOMMU

  • The vIOMMU must support DMA remapping (Intel VT-d, AMD-Vi)