ort-build

Building ONNX Runtime

The build scripts build.sh (Linux/macOS) and build.bat (Windows) delegate to tools/ci_build/build.py.

Build phases

Three phases, controlled by flags:

• --update — generate CMake build files
• --build — compile (add --parallel to speed this up)
• --test — run tests

For native builds, if none are specified (and --skip_tests is not passed), all three run by default. For cross-compiled builds, the default is --update + --build only.

When to use --update

You need --update when:

• First build in a new build directory
• New source files are added (some CMake targets use glob patterns, others use explicit file lists — re-run to pick up new files either way)
• CMake configuration changes (new flags, updated CMakeLists.txt)

You do not need --update when only modifying existing .cc/.h files — just use --build. Skipping it saves time.

Examples

# Full build (update + build + test)
./build.sh --config Release --parallel
.\build.bat --config Release --parallel     # Windows
 
# Just regenerate CMake files
./build.sh --config Release

Key flags

Build output path

Default: build/<Platform>/<Config>/ where Platform is Linux, MacOS, or Windows.

With Visual Studio multi-config generators, the config name appears twice (e.g., build/Windows/Release/Release/).

It may be customized with --build_dir.

Agent tips

• Activate a Python virtual environment before building. See "Python > Virtual environment" in AGENTS.md.
• Build flags can silently reroute which kernel/code path executes. A build option can change which kernel is compiled, and therefore which code path actually runs — so a CI failure can live in a different code path than your local build exercises. Before hypothesizing a hardware- or algorithm-specific cause (e.g. "this GPU arch miscomputes"), first identify which kernel actually ran for the failing configuration (see the ort-test skill → "Verify which path/kernel actually executed"). Concrete instance: onnxruntime_QUICK_BUILD=ON compiles FlashAttention for head_dim 128 only, so most attention shapes silently dispatch to Memory-Efficient Attention instead of Flash — details in the cuda-attention-kernel-patterns skill.
• Prefer python tools/ci_build/build.py directly over build.bat/build.sh when redirecting output. The .bat wrapper runs in cmd.exe, which breaks PowerShell redirection.
• Redirect output to a file (e.g., > build_log.txt 2>&1). Build output is large and will overflow terminal buffers.
• Run builds in the background — a full build can take tens of minutes to over an hour. Poll the log for "Build complete" or errors.
• Use --parallel by default unless the user says otherwise.
• Ask the user what they want to build (config, execution providers, wheel, etc.) if not clear from their prompt.