Skip to content

Install

Quick Start

heliaAOT ships as the helia-aot Python package on PyPI. Use pipx for an isolated CLI install, or install with uv / pip when that better fits your development workflow. From-source options are at the end.

Using pipx is the recommended way to install helia-aot as it allows installing and running Python CLIs in isolated environments. Upon installation, helia-aot will be available in your PATH. The pipx interpreter must be Python >=3.11.

  • Install helia-aot:

    pipx install helia-aot

  • Upgrade helia-aot: pipx upgrade helia-aot

  • Invoke helia-aot: helia-aot --help
  • Remove helia-aot: pipx uninstall helia-aot

Tip

pipx requires a local Python (see requirements below), but isolates heliaAOT from your global environment.

uv can install heliaAOT as an isolated tool from PyPI.

  • Install helia-aot:

    uv tool install helia-aot

  • Upgrade helia-aot: uv tool upgrade helia-aot

  • Invoke helia-aot: helia-aot --help
  • Remove helia-aot: uv tool uninstall helia-aot

Use pip inside a virtual environment when you want heliaAOT installed alongside project-specific Python tooling.

python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
python -m pip install helia-aot
helia-aot --help

If you want the latest, editable install for development, use one of the methods below.

git clone https://github.com/AmbiqAI/helia-aot.git
cd helia-aot
python -m venv .venv && source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -e .
helia-aot --help

git clone https://github.com/AmbiqAI/helia-aot.git
cd helia-aot
uv sync
uv run helia-aot --help

Verify the install

Once installed, verify the CLI is working:

helia-aot version
helia-aot --help

You should see usage text and a semantic version. If the command isn’t found, ensure the install location is on your PATH.

Requirements

Software (tooling)

  • For pipx, uv, and pip installs: Python >=3.11

The project’s Python dependencies are listed in pyproject.toml and are automatically handled by pipx, pip, or uv.

Firmware (for generated C modules)

See platform-specific integration guides:

Usage (CLI)

$ helia-aot --help

 Usage: helia-aot [OPTIONS] COMMAND [ARGS]...

 heliaAOT command line interface.

╭─ Options ────────────────────────────────────────────────────────────────────────────────────────╮
│ --help  -h        Show this message and exit.                                                    │
╰──────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ───────────────────────────────────────────────────────────────────────────────────────╮
│ version   Display the version of the heliaAOT library.                                           │
│ convert   Convert a model to standalone C inference module.                                      │
╰──────────────────────────────────────────────────────────────────────────────────────────────────╯

See the CLI Reference for all commands and flags.

Advanced: Install from source

If you want the latest, editable install for development, use one of the methods below.

git clone https://github.com/AmbiqAI/helia-aot.git
cd helia-aot
python -m venv .venv && source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -U pip setuptools wheel
pip install -e .
helia-aot --help

git clone https://github.com/AmbiqAI/helia-aot.git
cd helia-aot
uv sync
uv run helia-aot --help

Developer setup

Contributors should also install the test dependencies, the LFS model fixtures, and the git hooks that CI mirrors:

uv sync --group ci        # test + lint dependencies (also the venv ty reads)
git lfs pull              # model fixtures used by the test suite
uv tool install pre-commit
pre-commit install

pre-commit install covers the pre-commit stage (whitespace fixers, gitleaks, ruff, ty, the TODO(#123) marker check). To check the whole tree the way CI does, run pre-commit run --all-files.

The ty type check blocks the commit on any error-level diagnostic and runs with ty's default rule severities; a unit test pins the warning count at zero so it cannot creep back. It prints a one-line summary (full report in .pre-commit/ty.log) and resolves imports against .venv, so if you haven't run uv sync yet — or ran a bare uv venv without syncing — it prints a one-line skip with a hint instead.

Updating

  • pipx: pipx upgrade helia-aot
  • uv tool: uv tool upgrade helia-aot
  • pip: python -m pip install --upgrade helia-aot
  • source installs: pull main and reinstall (pip install -e . or uv sync)

Uninstall

  • pipx: pipx uninstall helia-aot
  • uv tool: uv tool uninstall helia-aot
  • pip: python -m pip uninstall helia-aot
  • source installs: remove the virtual environment and repo folder

Next Steps