Environment:Onnx Onnx Cpp Build Environment
| Knowledge Sources | |
|---|---|
| Domains | Infrastructure, Build_System |
| Last Updated | 2026-02-10 02:00 GMT |
Overview
C++17 build environment with CMake 3.26+, Protobuf compiler, and nanobind for building the ONNX C++ library and Python extension from source.
Description
This environment provides the build toolchain required to compile ONNX from source. The ONNX library has a C++ core that implements the model checker, shape inference engine, version converter, and text printer/parser. These components are exposed to Python via nanobind bindings (the `onnx_cpp2py_export` module). The build uses CMake as its primary build system and supports both system-provided and auto-fetched Protobuf. Ninja is preferred as the CMake generator on non-Windows platforms. Multiple build configuration environment variables control features like ML operators, exception handling, and static registration.
Usage
Use this environment when you need to build ONNX from source rather than installing from a pre-built wheel. This is required for:
- Contributing to ONNX C++ code
- Building for platforms without pre-built wheels
- Customizing the ONNX namespace (e.g., embedding in another project)
- Disabling features (exceptions, static registration)
- Building with AddressSanitizer or code coverage
System Requirements
| Category | Requirement | Notes |
|---|---|---|
| OS | Linux, macOS, or Windows | AIX also supported with special handling |
| C++ Compiler | C++17 compatible | GCC 7+, Clang 5+, MSVC 2017+ (v15.7+) |
| CMake | >= 3.26 | Must be on PATH as `cmake` or `cmake3` |
| Python | >= 3.10 | Required for protobuf code generation and Python bindings |
| Disk | ~500MB | Including protobuf fetch and build artifacts |
Dependencies
System Packages
- `cmake` >= 3.26
- C++17 compiler (g++, clang++, or MSVC)
- `ninja` (optional, recommended for non-Windows; enabled by default via `USE_NINJA=1`)
- `git` (for FetchContent dependencies)
- `protoc` (optional; auto-fetched from Protobuf v31.1 if not found)
Python Packages (Build)
- `setuptools` >= 77
- `protobuf` >= 4.25.1
- `nanobind` (optional; auto-fetched v2.10.2 if not found via CMake)
Automatically Fetched Dependencies
- Protobuf v31.1 - fetched if protoc is not found on the system
- nanobind v2.10.2 - fetched if not found via CMake find_package
- abseil-cpp - required by Protobuf >= 4.22.0, auto-fetched with Protobuf
- utf8_range - required by Protobuf >= 4.22.0
Credentials
No credentials required for building.
Quick Install
# Prerequisites (Ubuntu/Debian)
sudo apt-get install cmake g++ git ninja-build
# Build from source (basic)
git clone https://github.com/onnx/onnx.git
cd onnx
pip install -e .
# Build from source with custom options
ONNX_ML=1 ONNX_NAMESPACE=onnx pip install -e .
# Build with debug mode
DEBUG=1 pip install -e .
Code Evidence
CMake minimum version from `CMakeLists.txt:2`:
cmake_minimum_required(VERSION 3.26)
C++17 requirement from `CMakeLists.txt:80-86`:
if(NOT DEFINED CMAKE_CXX_STANDARD)
set(CMAKE_CXX_STANDARD 17)
else()
if(CMAKE_CXX_STANDARD VERSION_LESS 17)
message(FATAL_ERROR "At least C++17 is required.")
endif()
endif()
Build system requirements from `pyproject.toml:6`:
requires = ["setuptools>=77", "protobuf>=4.25.1"]
CMake assertion from `setup.py:176`:
assert CMAKE, "Could not find cmake in PATH"
Environment variable configuration from `setup.py:42-53`:
ONNX_ML = os.getenv("ONNX_ML") != "0"
ONNX_VERIFY_PROTO3 = os.getenv("ONNX_VERIFY_PROTO3") == "1"
ONNX_NAMESPACE = os.getenv("ONNX_NAMESPACE", "onnx")
ONNX_BUILD_TESTS = os.getenv("ONNX_BUILD_TESTS") == "1"
ONNX_DISABLE_EXCEPTIONS = os.getenv("ONNX_DISABLE_EXCEPTIONS") == "1"
ONNX_DISABLE_STATIC_REGISTRATION = os.getenv("ONNX_DISABLE_STATIC_REGISTRATION") == "1"
ONNX_PREVIEW_BUILD = os.getenv("ONNX_PREVIEW_BUILD") == "1"
USE_MSVC_STATIC_RUNTIME = os.getenv("USE_MSVC_STATIC_RUNTIME", "0") == "1"
USE_NINJA = os.getenv("USE_NINJA", "1") != "0"
DEBUG = os.getenv("DEBUG", "0") == "1"
COVERAGE = os.getenv("COVERAGE", "0") == "1"
Exceptions incompatible with Python bindings from `setup.py:233-236`:
if "-DONNX_DISABLE_EXCEPTIONS=ON" in cmake_args:
raise RuntimeError(
"-DONNX_DISABLE_EXCEPTIONS=ON option is only available for c++ builds. "
"Python binding require exceptions to be enabled."
)
Common Errors
| Error Message | Cause | Solution |
|---|---|---|
| `AssertionError: Could not find cmake in PATH` | CMake is not installed | Install cmake >= 3.26: `sudo apt-get install cmake` |
| `FATAL_ERROR: At least C++17 is required.` | C++ compiler too old | Upgrade compiler to GCC 7+, Clang 5+, or MSVC 2017+ |
| `RuntimeError: -DONNX_DISABLE_EXCEPTIONS=ON option is only available for c++ builds` | Attempted to disable exceptions with Python bindings | Only use `ONNX_DISABLE_EXCEPTIONS=1` for pure C++ builds without Python |
| `protobuf compiler not found` | Neither system protoc nor FetchContent available | Install protobuf or ensure internet access for FetchContent download |
| `nanobind not found while FETCHCONTENT_FULLY_DISCONNECTED is ON` | Offline build without nanobind | Install nanobind locally or set `nanobind_DIR` |
Compatibility Notes
- Windows (MSVC): Uses `/EHsc` exception handling, `/MP` for parallel compilation, `/utf-8` for Unicode source files. Supports both static and shared MSVC runtime via `USE_MSVC_STATIC_RUNTIME`.
- Windows ARM: Detected via `platform.machine()` and configured with `-A ARM64` or `-A ARM`.
- AIX: Special handling with `CMAKE_NO_SYSTEM_FROM_IMPORTED=1`.
- Cross-compilation: Requires separate Python interpreter and development packages; detected automatically by CMake.
- Unity builds: Optional via `ONNX_USE_UNITY_BUILD=ON`; two files (`schema.cc`, `tensor_proto_util.cc`) are excluded due to template specialization ordering issues.