Skip to content

getting-started.md

Latest commit

 

History

History
292 lines (223 loc) · 9.77 KB

getting-started.md

File metadata and controls

292 lines (223 loc) · 9.77 KB
Raw

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 matching the selected wheel. Public PyPI and S3 light hardware wheels are built for Python 3.10 and Python 3.12. The wheel targets a specific CPython ABI, so the venv's Python must match. Invoke python3.12 or python3.10 explicitly rather than the system default python3:

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

On Linux x86_64 machines with Tenstorrent hardware:

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.

Tenstorrent 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/tt-lang/.

Tenstorrent S3 wheels use browsable wheel views (--find-links):

  • Nightly development wheels are under tt-lang/<YYYY-MM>/, the year-month of the version's devYYYYMMDD suffix (e.g. version X.Y.Z.dev20260615 -> tt-lang/2026-06/).
  • Stable S3 release wheels are under tt-lang/releases/.
  • Light wheels built and device-tested against a specific tt-metal commit are under tt-lang/ttmetal/<ttmetal7>/, that commit's 7-character prefix.

The bundled-wheel example below installs a scheduled development wheel. Stable S3 releases use TTLANG_VERSION=X.Y.Z and https://pypi.eng.aws.tenstorrent.com/tt-lang/releases/.

The default S3-hosted 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-s3-version>
pip install \
  --find-links https://pypi.eng.aws.tenstorrent.com/tt-lang/<YYYY-MM>/ \
  --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.

A per-tt-metal-SHA light wheel resolves from that commit's directory with --find-links; a scheduled light wheel resolves from its tt-lang/<YYYY-MM>/ directory with --find-links as well:

TTLANG_VERSION=<published-s3-version>
pip install \
  --find-links https://pypi.eng.aws.tenstorrent.com/tt-lang/ttmetal/<ttmetal7>/ \
  --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__)'

Print the exact source revisions the wheel was built from (include this when filing issues):

python -c 'import ttl; print(ttl.build_info())'

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-24-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-24-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.10+ (Python 3.12 recommended)
  • 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