Getting Started

The fastest way to get started with TT-Lang is to install a pre-built package from PyPI. To develop TT-Lang itself or debug the compiler, use the Docker images or build from source.

Install from PyPI

We provide two TT-Lang packages: the tt-lang package includes the TT-Lang compiler and Tenstorrent hardware support and depends on ttnn, pytorch, and several smaller Python packages, while tt-lang-sim includes only the functional simulator (no compiler or hardware support) and does not depend on ttnn.

First, create an isolated Python environment (venv, conda, etc.) with Python 3.11 or later (Python 3.12 recommended). The wheel targets a specific CPython ABI, so the venv’s Python must match — invoke python3.12 (or python3.11) explicitly rather than the system default python3:

python3.12 -m venv --prompt ttlang ttlang-venv
source ttlang-venv/bin/activate

On Linux machines with Tenstorrent hardware (Linux x86_64 / aarch64):

pip install tt-lang
tt-lang-setup                     # install matching sfpi runtime + copy tutorials

Functional simulator only on Linux or macOS, does not require Tenstorrent hardware:

pip install tt-lang-sim
tt-lang-setup                     # copy bundled tutorials to ./tutorials/

tt-lang-setup is idempotent (safe to run multiple times). Inside the venv it:

Downloads the sfpi compiler that pairs with the installed ttnn and extracts it under <venv>/.../ttnn/runtime/sfpi/ (only for the tt-lang package).
Copies bundled tutorials (elementwise, matmul, broadcast) to ./tutorials/.

For finer control, tt-lang-setup-sfpi runs only the sfpi step and tt-lang-setup-tutorials -t <DIR> only the tutorials copy.

Internal S3 wheels

More frequently updated development versions of tt-lang are available from Tenstorrent’s S3 PyPI index.

Set TTLANG_VERSION to a published version from the workflow summary or the S3 package index. A version selector is required because public PyPI also hosts tt-lang, and pip resolves candidates across all configured indexes. Available versions are listed at https://pypi.eng.aws.tenstorrent.com/.

The default internal tt-lang wheel bundles the ttnn artifacts from the toolchain used to build the wheel, so pip install does not pull ttnn from PyPI. As with the public wheel, tt-lang-setup then installs the matching sfpi runtime and copies the tutorials:

TTLANG_VERSION=<published-internal-version>
pip install \
  --extra-index-url https://pypi.eng.aws.tenstorrent.com/ \
  --extra-index-url https://download.pytorch.org/whl/cpu \
  "tt-lang==$TTLANG_VERSION"
tt-lang-setup    # downloads sfpi into the bundled ttnn tree + copies tutorials

Use tt-lang-light only when the environment already has a newer local tt-metal source or install layout that should provide ttnn. The package is a metapackage: tt-lang-light==X depends on the matching no-ttnn core wheel tt-lang==X+light. Install either tt-lang or tt-lang-light in an environment, not both.

TTLANG_VERSION=<published-internal-version>
pip install \
  --extra-index-url https://pypi.eng.aws.tenstorrent.com/ \
  --extra-index-url https://download.pytorch.org/whl/cpu \
  "tt-lang-light==$TTLANG_VERSION"
tt-lang-setup    # copies tutorials only; sfpi is provided by the external tt-metal

The tt-lang-setup command above copies the tutorials into ./tutorials. Configure a native tt-metal source/build layout before running those local hardware examples. The --check option imports ttnn from the selected tree, so use it only with trusted tt-metal builds:

external_tt_metal_env="$(
  tt-lang-setup-external-tt-metal \
    --tt-metal-dir /path/to/tt-metal \
    --build-dir /path/to/tt-metal/build \
    --check
)" && eval "$external_tt_metal_env"

Configure an install-layout tt-metal prefix similarly:

external_tt_metal_env="$(
  tt-lang-setup-external-tt-metal \
    --tt-metal-dir /path/to/tt-metal-install \
    --check
)" && eval "$external_tt_metal_env"
python tutorials/elementwise/step_4_multinode_grid_full.py
python tutorials/matmul/step_3_multinode.py

Validate that Python resolves both packages from the intended environment:

python -c 'import ttnn, ttl; print(ttnn.__file__, ttl.__version__)'

Run a tutorial example:

tt-lang-sim tutorials/elementwise/step_4_multinode_grid_full.py    # simulator (no compilation, runs on CPU)
python tutorials/elementwise/step_4_multinode_grid_full.py        # compiles and runs on hardware

Build from source for the simulator only

To run the simulator from a source checkout without installing the PyPI package:

git clone https://github.com/tenstorrent/tt-lang.git
cd tt-lang
cmake -G Ninja -B build -DTTLANG_SIM_ONLY=ON
cmake --build build
source build/env/activate
tt-lang-sim examples/eltwise_add.py

Docker quick start

Two images are available:

Image	Purpose	Can run TT-Lang programs?	Can build TT-Lang?
dist	Run TT-Lang programs	Yes	No
ird	Develop and build from source	Yes	Yes

Running programs (dist image)

The dist image contains a fully built TT-Lang installation at /opt/ttlang-toolchain. Use it to compile and run TT-Lang programs without building anything.

docker run -d --name $USER-dist \
  --device=/dev/tenstorrent/0:/dev/tenstorrent/0 \
  -v /dev/hugepages:/dev/hugepages \
  -v /dev/hugepages-1G:/dev/hugepages-1G \
  -v $HOME:$HOME \
  ghcr.io/tenstorrent/tt-lang/tt-lang-dist-ubuntu-22-04:latest \
  sleep infinity

docker exec -it $USER-dist /bin/bash

The environment activates automatically on login. Run an example immediately:

python /opt/ttlang-toolchain/examples/elementwise-tutorial/step_4_multinode_grid_full.py

Building from source (ird image)

The ird image has the pre-built toolchain (LLVM, tt-metal, Python venv) but does not include TT-Lang itself. Clone and build against the toolchain:

docker run -d --name $USER-ird \
  --device=/dev/tenstorrent/0:/dev/tenstorrent/0 \
  -v /dev/hugepages:/dev/hugepages \
  -v /dev/hugepages-1G:/dev/hugepages-1G \
  -v $HOME:$HOME \
  -v $SSH_AUTH_SOCK:/ssh-agent -e SSH_AUTH_SOCK=/ssh-agent \
  ghcr.io/tenstorrent/tt-lang/tt-lang-ird-ubuntu-22-04:latest \
  sleep infinity

docker exec -it $USER-ird /bin/bash

Inside the container:

git clone https://github.com/tenstorrent/tt-lang.git
cd tt-lang
cmake -G Ninja -B build -DTTLANG_USE_TOOLCHAIN=ON
source build/env/activate
cmake --build build

Verify the build and run an example:

ninja -C build check-ttlang-all
python examples/elementwise-tutorial/step_4_multinode_grid_full.py

Building without Docker

Prerequisites

CMake 3.28+, Ninja, and Clang 17+ or GCC 12+
Python 3.11+
For faster builds: a pre-built toolchain at TTLANG_TOOLCHAIN_DIR (default /opt/ttlang-toolchain). Without one, LLVM and tt-metal build from submodules on first configure.

With pre-built toolchain

cmake -G Ninja -B build -DTTLANG_USE_TOOLCHAIN=ON
source build/env/activate
cmake --build build

From submodules

cmake -G Ninja -B build
source build/env/activate
cmake --build build

See the build system documentation for all supported build modes and CMake options.

Functional simulator

TT-Lang includes a functional simulator that runs operations as pure Python without requiring Tenstorrent hardware or the full compiler stack. Use it to validate kernel logic and debug with any Python debugger:

tt-lang-sim examples/eltwise_add.py
python -m pytest test/sim/

The simulator typically supports more language features than the compiler at any given point — see the functionality matrix for current coverage. See the programming guide for debugger setup and more details.

Quick checks

Full compiler suite: ninja -C build check-ttlang-all
MLIR tests only: ninja -C build check-ttlang-mlir
Single MLIR test: llvm-lit test/ttlang/Dialect/TTL/IR/ops.mlir
Simulator tests: python -m pytest test/sim -q (not included in check-ttlang-all)

Next steps

Take a tour to get an introduction to TT-Lang features from single-tile to multinode operations
Read the programming guide for compiler options, print debugging, and performance tools
Use Claude Code with the built-in slash commands to translate kernels, profile, and optimize
Explore the examples/ directory for complete working programs