Push GPU kernels further with NVIDIA compiler tuning.
CompileIQ is a hyperparameter optimizer for NVIDIA compiler controls and application parameters. It helps kernel developers tune those controls against workload-specific benchmarks, adding another optimization path for CUDA C++, Triton, and Helion kernels after source-level tuning has plateaued.
Documentation | PyPI | Latest Release | Search Space Catalog Releases | Booster Pack Catalog Releases
CompileIQ tunes NVIDIA compilers to your workload using the compiler's Advanced Controls interface. At a high level CompileIQ:
- Searches optimal PTXAS and NVCC Advanced Controls for your target kernel.
- Iteratively measures candidates against metrics defined by you (runtime, compile time, power, etc).
- Produces an Advanced Control File (ACF) that can be distributed with the kernel.
- Supports CUDA C++, Triton, and Helion tuning workflows.
- Define the kernel benchmark and objective.
- Run CompileIQ over the relevant compiler controls.
- Apply the generated ACF in future builds or JIT compilation.
Tune the compiler to the workload.
See the documentation and examples for more.
You can either install through PyPI:
pip install compileiqThe CompileIQ 1.1 release contract is one complete distribution: each published
platform wheel contains the native amber engine, which is the default
and the only bundled engine, with no separate runtime package to install.
In CompileIQ 1.1, amber replaces the original search core.
For editable development, make install installs the frontend and materializes
the pinned native payload checked into this repository through Git LFS, so fetch
the LFS objects first:
git lfs pull
make installmake install-frontend installs the frontend without an engine, which is enough
for linting, type checking, and unit tests.
CompileIQ 1.1 targets Python 3.11, 3.12, 3.13, and 3.14. The beta CI matrix
composes, verifies, and clean-installs complete wheels for Linux x86_64, Linux
ARM64, Windows AMD64, and macOS ARM64 on each of those Python versions. Every
cell provides the same amber engine.
Linux wheels target glibc 2.34 or newer and are tagged manylinux_2_34. See
the installation guide for Linux runtime library
requirements and Windows runtime notes.
CompileIQ can retrieve curated compiler search spaces from GitHub release assets and cache them locally. Use PtxasSearchSpace or NvccSearchSpace to select a compiler, compiler version, and optional variant:
from compileiq.search_spaces.compilers import PtxasSearchSpace
search_space = PtxasSearchSpace(version="13.3", variant="att")For reproducible runs, pin a search-space release tag:
search_space = PtxasSearchSpace(version="13.3", tag="search-spaces-2026.05.05")Set CIQ_SEARCH_SPACES_DIR to use a local mirror containing manifest.json plus the referenced .bin files. Set CIQ_SEARCH_SPACES_REPO to test or use a different release repository.
Browse the published Search Space Catalog Releases to inspect available catalog assets and release notes.
| Environment Variable | Default Value | Type | Description |
|---|---|---|---|
| CIQ_KEEP_CACHE | False | bool | If set to True, .cache files will not be deleted. |
| CIQ_PROCESS_MODE | "forkserver" | str | Start method for process-based workers. Set to "fork" for tighter process separation when threads are involved. IsoMultiProcessWorker defaults to "fork" independently. |
| CIQ_SEARCH_SPACES_DIR | unset | path | Reads compiler search-space manifest.json and .bin files from a local mirror instead of GitHub. |
| CIQ_SEARCH_SPACES_REPO | NVIDIA/CompileIQ | str | GitHub repository used for search-space release lookups, useful for staging or a future dedicated asset repo. |
The examples/ folder has simple examples for you to get started on using CompileIQ.
For the full user guide, see the CompileIQ documentation.
If you are planning on running examples, you may need additional dependencies:
python -m poetry install --with examplesInstall the docs dependencies once:
make install-docsTo preview uncommitted documentation edits from your live worktree:
make docs-previewThen open http://localhost:8000/main/.
If port 8000 is already in use, stop the existing local docs server first.
Use make docs or make docs-serve when you need to test the multiversion
documentation shape used by GitHub Pages. Those commands build from Git refs, so
they are not the right choice for checking dirty worktree edits before commit.
