Skip to content

Using the tt‐metalium container

Jump to bottom
June Knauth edited this page Feb 2, 2026 · 11 revisions

Why containers?

A container is the easiest way to install tt-metalium because it has a complex set of dependencies which are not available on some distributions and systems. To help mitigate some of the UX challenges containers raise, we create a "wrapper script" which is located at ~/.local/bin/tt-metalium. The script uses your container runtime (Podman or Docker) to launch the container with some useful options preset for you. Here's the command we use:

docker run --rm -it \
  --privileged \
  --volume=/dev/hugepages-1G:/dev/hugepages-1G \
  --volume=${HOME}:/home/user \
  --device=/dev/tenstorrent:/dev/tenstorrent \
  --workdir=/home/user \
  --env=DISPLAY=${DISPLAY} \
  --env=HOME=/home/user \
  --env=TERM=${TERM:-xterm-256color} \
  --network=host \
  --security-opt label=disable \
  --entrypoint /bin/bash \
  "ghcr.io/tenstorrent/tt-metal/tt-metalium-ubuntu-22.04-release-amd64:latest-rc" "$@"

This ensures that:

  • The container has access to hugepages
  • The container has access to your tenstorrent devices
  • You can read and write your home directory as yourself
  • Networking is as simple as possible
  • Any commands you pass to the script are executed when the container starts

Modifying your container setup

By modifying the wrapper script at ~/.local/bin/tt-metalium, you can edit the configuration options passed to the container at runtime. You can also edit the image itself or launch the container manually like you would any other.

Podman vs Docker

The installer supports both Podman (default) and Docker as container runtimes.

Podman is the default because it's easier to install (packaged by all major distributions), can run without administrator privileges, and automatically maps UIDs and GIDs between the container and the host system. This means that when you create or edit a file in your home directory from within the container, the host system attributes the changes to your user, not the administrator, which prevents file permissions issues.

Docker can be installed instead by using --install-container-runtime=docker. If you already have Docker or Podman installed, you can use --install-container-runtime=no to skip installation and use your existing setup.

Clone this wiki locally