Getting Started¶

The fastest way to get started with TT-Lang is with the functional simulator, which runs operations as pure Python — no Tenstorrent hardware, no compiler build required:

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

To compile and run operations on hardware, use a pre-built Docker image or build from source as described below.

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 11+
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