TT-Lensium :tm:
A low-level hardware debugger
A low-level debugging tool for Tenstorrent hardware that enables direct access to and communication with Wormhole and Blackhole devices.
Quickstart
You can install latest published version with:
pip install tt-exalens
Or specific version with:
pip install tt-exalens=="x.y.z"
Alternatively, you can install the latest code from GitHub with:
pip install git+https://github.com/tenstorrent/tt-exalens.git
The CLI application can be run by invoking the tt-exalens command after installing the wheel.
Running the CLI application
The CLI application can be run via the tt-exalens.py script or by invoking the tt-exalens command after installing the wheel.
The application supports both local and remote device access. For remote connections, a server instance must be started using the same application.
A GDB server can be launched, enabling stepping, breakpoints, and other debugging features via a GDB client.
For more usage information, refer to the tutorial or the documentation.
Using library
The application functionality is also available through the ttexalens Python library, enabling you to create custom scripts that interact with Tenstorrent hardware.
For a quick start with the library, check out the tutorial. Full documentation is also available here.
Development
Setting up environment
The recommended way to manage dependencies is by creating a virtual environment with:
./scripts/create-venv.sh
To activate the created environment, use:
.venv/bin/activate
Alternatively, you can use your existing environment and just install dependencies with:
./scripts/install-deps.sh
Testing
Test requirements
The following dependencies are required to build the necessary kernels:
- ninja-build,
- cmake
- make
Running tests
The easiest way to run all tests locally is by using the make wrapper from the project root directory:
make test
This command will build dependencies, run all tests, create the wheel, and run wheel tests.
If you don't need all of these steps, you can run them manually:
# Compile kernels that tests use
make
# Install runtime dependencies
pip install -r ttexalens/requirements.txt
# Install test dependencies
pip install -r test/test_requirements.txt
# Run library tests
pytest test/ttexalens
# Run CLI application tests
pytest test/app
If you're developing with VSCode (or its derivatives), you can use the Testing extension. Install the Python extension to enumerate all tests within the Testing tab in the activity bar.
Updating documentation
Library documentation is automatically generated from source code docstrings. To update the library documentation, run the following command in your development environment:
make docs
in the project root.
For more advanced use cases, refer to the source code of the documentation generation scripts, located in docs/bin.
Static checks
Pre-commit
We have defined various pre-commit hooks that check the code for formatting, licensing issues, etc.
To install pre-commit, run the following command:
pip install pre-commit
After installing pre-commit, you can install the hooks by running:
pre-commit install
Now, each time you run git commit the pre-commit hooks (checks) will be executed.
If you have already committed before installing the pre-commit hooks, you can run on all files to "catch up":
pre-commit run --all-files
For more information visit pre-commit
mypy
We use mypy for static code analysis.
You can use the make wrapper to execute it with:
make mypy
Or run it directly from your development environment with:
mypy
1 maintainer
Metadata
1 maintainer
Release files for tt-exalens 0.4.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Built distributions (wheels)
| File | Reset | |||
|---|---|---|---|---|
| tt_exalens-0.4.0-cp313-cp313-manylinux_2_34_x86_64.whl | CPython 3.13 | CPython 3.13 | Linux glibc 2.34+ x86-64 | Details |
| tt_exalens-0.4.0-cp313-cp313-manylinux_2_34_aarch64.whl | CPython 3.13 | CPython 3.13 | Linux glibc 2.34+ ARM64 | Details |
| tt_exalens-0.4.0-cp312-cp312-manylinux_2_34_x86_64.whl | CPython 3.12 | CPython 3.12 | Linux glibc 2.34+ x86-64 | Details |
| tt_exalens-0.4.0-cp312-cp312-manylinux_2_34_aarch64.whl | CPython 3.12 | CPython 3.12 | Linux glibc 2.34+ ARM64 | Details |
| tt_exalens-0.4.0-cp311-cp311-manylinux_2_34_x86_64.whl | CPython 3.11 | CPython 3.11 | Linux glibc 2.34+ x86-64 | Details |
| tt_exalens-0.4.0-cp311-cp311-manylinux_2_34_aarch64.whl | CPython 3.11 | CPython 3.11 | Linux glibc 2.34+ ARM64 | Details |
| tt_exalens-0.4.0-cp310-cp310-manylinux_2_34_x86_64.whl | CPython 3.10 | CPython 3.10 | Linux glibc 2.34+ x86-64 | Details |
| tt_exalens-0.4.0-cp310-cp310-manylinux_2_34_aarch64.whl | CPython 3.10 | CPython 3.10 | Linux glibc 2.34+ ARM64 | Details |
Total release size: 7.6 MB
Release files / tt_exalens-0.4.0-cp313-cp313-manylinux_2_34_x86_64.whl
| Download URL | tt_exalens-0.4.0-cp313-cp313-manylinux_2_34_x86_64.whl |
|---|---|
| Size | 970.1 kB |
| Tags | CPython 3.13 Linux glibc 2.34+ x86-64 |
|
SHA-256 checksum How to use checksums |
59612872f2e08739a195038a9fa6c984335fbc84c2410ebb461dd14fc2daab61
|
|
BLAKE2b-256 checksum How to use checksums |
ef53e8c9549e55d319a6335714a985efac6aae101e071aca8a1b8f37fd28f66d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 9, 2026.
Transparency logRelease files / tt_exalens-0.4.0-cp313-cp313-manylinux_2_34_aarch64.whl
| Download URL | tt_exalens-0.4.0-cp313-cp313-manylinux_2_34_aarch64.whl |
|---|---|
| Size | 934.5 kB |
| Tags | CPython 3.13 Linux glibc 2.34+ ARM64 |
|
SHA-256 checksum How to use checksums |
fb88b319058e7e85e92b1babc11a20fbe7433f3838a13361042b13fc808edaf8
|
|
BLAKE2b-256 checksum How to use checksums |
7506926e3f3acdbeb35d19bbee9baa6e5772c70ac933703c1c457f759b90fc92
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 9, 2026.
Transparency logRelease files / tt_exalens-0.4.0-cp312-cp312-manylinux_2_34_x86_64.whl
| Download URL | tt_exalens-0.4.0-cp312-cp312-manylinux_2_34_x86_64.whl |
|---|---|
| Size | 970.2 kB |
| Tags | CPython 3.12 Linux glibc 2.34+ x86-64 |
|
SHA-256 checksum How to use checksums |
9c50a0b50c3316afb900e30719036f7c942c2e4ae13d441b4266de61483f38f4
|
|
BLAKE2b-256 checksum How to use checksums |
cac31ffdc3c82e55f4d3cb768db0f09f78a34464d1126f212e6448ea1ab48fc2
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 9, 2026.
Transparency logRelease files / tt_exalens-0.4.0-cp312-cp312-manylinux_2_34_aarch64.whl
| Download URL | tt_exalens-0.4.0-cp312-cp312-manylinux_2_34_aarch64.whl |
|---|---|
| Size | 934.6 kB |
| Tags | CPython 3.12 Linux glibc 2.34+ ARM64 |
|
SHA-256 checksum How to use checksums |
bee50af25cfc6dce9223b7b3b2c924f37f46a8e8001ffd216cc3de26d3bb689f
|
|
BLAKE2b-256 checksum How to use checksums |
bfdfd861d006c3427aec946a31f7bb64ea974aa18c1f5537a681f0dfc04d3dc3
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 9, 2026.
Transparency logRelease files / tt_exalens-0.4.0-cp311-cp311-manylinux_2_34_x86_64.whl
| Download URL | tt_exalens-0.4.0-cp311-cp311-manylinux_2_34_x86_64.whl |
|---|---|
| Size | 970.7 kB |
| Tags | CPython 3.11 Linux glibc 2.34+ x86-64 |
|
SHA-256 checksum How to use checksums |
a819284dd864e595b822722668ac11201df74962c5cb735d8a925c1015468878
|
|
BLAKE2b-256 checksum How to use checksums |
226b747b2346161575165357dadabf1f7b06ef282184d09a107e2abea4e24fa5
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 9, 2026.
Transparency logRelease files / tt_exalens-0.4.0-cp311-cp311-manylinux_2_34_aarch64.whl
| Download URL | tt_exalens-0.4.0-cp311-cp311-manylinux_2_34_aarch64.whl |
|---|---|
| Size | 935.3 kB |
| Tags | CPython 3.11 Linux glibc 2.34+ ARM64 |
|
SHA-256 checksum How to use checksums |
4d600289f22faee07fb23b05ad5066923169f113e8b788ebcff5488c272beff2
|
|
BLAKE2b-256 checksum How to use checksums |
f51d13df487568c4cdeddee381b1b8591bec5199a6898278b04c01ee89a49899
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 9, 2026.
Transparency logRelease files / tt_exalens-0.4.0-cp310-cp310-manylinux_2_34_x86_64.whl
| Download URL | tt_exalens-0.4.0-cp310-cp310-manylinux_2_34_x86_64.whl |
|---|---|
| Size | 970.5 kB |
| Tags | CPython 3.10 Linux glibc 2.34+ x86-64 |
|
SHA-256 checksum How to use checksums |
5dfccc4806737f5875b672c8c6f013d779e2028ab7af3151a9cfb65824162d00
|
|
BLAKE2b-256 checksum How to use checksums |
067dd1f842244fe43ac83efaaea2678ea570d7d3bd0ffbb4c7dd03578cb3258d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 9, 2026.
Transparency logRelease files / tt_exalens-0.4.0-cp310-cp310-manylinux_2_34_aarch64.whl
| Download URL | tt_exalens-0.4.0-cp310-cp310-manylinux_2_34_aarch64.whl |
|---|---|
| Size | 935.1 kB |
| Tags | CPython 3.10 Linux glibc 2.34+ ARM64 |
|
SHA-256 checksum How to use checksums |
7aa3ffc330ff51475f1bb0b7453e203d5167a69fd98be69113b9d625b6a0e288
|
|
BLAKE2b-256 checksum How to use checksums |
5026c61950d1e789860e6fcf45216583c9c3c7beccb46b9a4e5f7d25f20b573d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 9, 2026.
Transparency log
