trtcheck 1.0.0

Static pre-flight checker for ONNX -> TensorRT conversion.

trtcheck

Static pre-flight checker for ONNX to TensorRT conversion. Full docs at https://sohams25.github.io/trtcheck/.

trtcheck reads an ONNX file, runs five independent checkers against it, and tells you in seconds whether the model will convert cleanly to a TensorRT engine. If it won't, the report explains what to fix. It runs anywhere Python runs: no TensorRT, no CUDA driver, no GPU required.

Why

The PyTorch -> ONNX -> TensorRT pipeline fails most of the time on the last hop. The errors are cryptic and the iteration loop ("export, wait two minutes, read a C++ traceback, google, try again") burns hours per fix.

trtcheck predicts the failure modes locally so you can correct them before invoking trtexec.

Install

pip install trtcheck

Or from source:

git clone https://github.com/sohams25/trtcheck.git
cd trtcheck
pip install -e ".[dev]"

Requires Python 3.10+.

Usage

# Basic check (defaults to TensorRT 10.3)
trtcheck model.onnx

# Target a specific TensorRT version
trtcheck model.onnx --target-trt 8.6

# Machine-readable output for CI
trtcheck model.onnx --format json --output report.json

# Self-contained HTML report
trtcheck model.onnx --format html --output report.html

# Filter to blockers only
trtcheck model.onnx --severity critical

# Compare two versions of a model (before/after a fix)
trtcheck before.onnx after.onnx --diff

# Auto-fix simple issues (INT64 indices, UINT8 inputs followed by Cast)
trtcheck model.onnx --fix --dry-run --output model_fixed.onnx
trtcheck model.onnx --fix --output model_fixed.onnx

Exit code is 1 if conversion is unlikely to succeed, 0 otherwise. Wire that into CI to catch regressions at PR time.

What it checks

Checker	Catches
operator support	Ops missing or partial in the target TRT version (e.g. SequenceEmpty, GroupNormalization on TRT 8.x)
precision	UINT8/FLOAT64/STRING inputs, INT64 weights, BF16 on older targets
dynamic shapes	Multiple symbolic dims on inputs
control flow	Loop with runtime trip count, nested Loop, If, Scan
graph structure	Empty outputs, duplicate node names, oversized constants

Each finding includes a specific remediation, not just "this is bad."

Using trtcheck as a GitHub Action

trtcheck ships a composite GitHub Action that runs on PRs touching *.onnx files and posts a sticky comment summarizing the report.

Add two workflows to your consumer repo. Workflow A runs against the PR head with read-only permissions; Workflow B posts the comment using the base repo's token. This dual-workflow pattern keeps fork PRs safe.

.github/workflows/trtcheck.yml:

name: trtcheck
on:
  pull_request:
    paths: ["**/*.onnx"]
permissions:
  contents: read
jobs:
  analyze:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with: { fetch-depth: 0 }
      - id: trtcheck
        uses: sohams25/trtcheck@v0.4.0
        with:
          target-trt: "10.3"
          fail-on: "critical"
      - if: always()
        run: |
          mkdir -p comment-artifact
          cp "${{ steps.trtcheck.outputs.comment-md }}" comment-artifact/body.md
          echo "${{ github.event.pull_request.number }}" > comment-artifact/pr-number.txt
      - if: always()
        uses: actions/upload-artifact@v4
        with: { name: trtcheck-comment, path: comment-artifact/ }

.github/workflows/trtcheck-comment.yml (see .github/workflows/example-consumer/trtcheck-comment.yml for the full template). It downloads the artifact from Workflow A and posts the sticky comment.

Inputs

Input	Default	Purpose
version	0.4.0	trtcheck PyPI version to install
target-trt	10.3	--target-trt value
severity	warning	--severity filter
fail-on	critical	exit policy: critical, warning, or never
paths	**/*.onnx	glob of files to consider
changed-only	true	only analyze PR-changed files

Outputs

report-json, comment-md, critical-count, warning-count, status (pass or fail).

How the operator matrix is maintained

The TRT-version-to-operator support table lives in trtcheck/data/operator_matrix.json and is hand curated. To refresh it for a new TensorRT release:

1. Edit tools/build_operator_matrix.py (the source of truth).
2. Run python tools/build_operator_matrix.py to regenerate the JSON.
3. Run the test suite: pytest tests/test_data_files.py -v.
4. Commit both the script change and the regenerated JSON.

Checking drift against upstream

tools/check_matrix_drift.py fetches the official ONNX-TensorRT operators.md from GitHub and flags any drift against our bundled matrix:

python tools/check_matrix_drift.py                   # online fetch
python tools/check_matrix_drift.py --local docs.md   # offline file
python tools/check_matrix_drift.py --target 10.0     # different TRT col

Exit code 1 (with a line-per-drift summary) when drift is detected, 0 when the matrix is in sync. Run it before cutting a release to keep the matrix honest.

Development

# Set up
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

# Tests
./scripts/run-tests.sh

# Type check
mypy trtcheck/

# Format
black . && isort .

If you contribute a new checker, follow the TDD cycle: write the test first, confirm it fails, then implement. See CLAUDE.md for the full project conventions.

Plugins (v1.0+)

Third-party packages can ship checkers, fixers, and reporters via Python entry-points:

[project.entry-points."trtcheck.fixers"]
strip_identity = "your_package.fixers:StripIdentityFixer"

The Protocols live in trtcheck.plugins. See docs/design/plugin-sdk.md for the full surface and examples/trtcheck-extra-fixers/ for a worked example. Use trtcheck --list-plugins to confirm a plugin loaded; --disable-plugin NAME filters one out without uninstalling.

Roadmap

• HTML diff view with side-by-side columns.
• Quarterly refresh tooling driven by NVIDIA release notes.

See CHANGELOG.md for release notes.

License

MIT. See LICENSE.