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):

python3 -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-host runs only the sfpi step and tt-lang-setup-tutorials -t <DIR> only the tutorials copy.

Run a tutorial example:

ttlang-sim tutorials/elementwise/step_4_multinode_grid_auto.py    # simulator (no compilation, runs on CPU)
python tutorials/elementwise/step_4_multinode_grid_auto.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
ttlang-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_auto.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_auto.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:

ttlang-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