Environment:Tencent Ncnn Build Environment

Knowledge Sources	ncnn Build Guide
Domains	Infrastructure, Build_System
Last Updated	2026-02-09 19:00 GMT

Overview

Cross-platform C++ build environment for compiling the ncnn inference library and its tools, requiring CMake 2.8.12+, a C++11-capable compiler, and optional SIMD instruction set support.

Description

This environment defines the base requirements for building ncnn from source on any supported platform (Linux, Windows, macOS, Android, iOS, WebAssembly, RISC-V, LoongArch). The ncnn library is a pure C++ project with no mandatory external dependencies beyond a C++ compiler and CMake. Optional features like OpenMP threading, Vulkan GPU compute, and Python bindings add additional requirements. The build system supports extensive cross-compilation via CMake toolchain files and produces both static and shared libraries.

Usage

Use this environment for any task that requires compiling ncnn from source, including building the core library, the model conversion tools (caffe2ncnn, onnx2ncnn, ncnnoptimize, ncnn2table, ncnn2int8), the benchmark executable, or the example applications. This is the mandatory prerequisite for all Implementation pages that reference ncnn C++ source files.

System Requirements

Category	Requirement	Notes
OS	Linux, Windows, macOS, Android, iOS, WebAssembly	Broad cross-platform support
CMake	>= 2.8.12	3.15+ recommended for MSVC runtime control; 3.4+ for Python bindings
C++ Compiler	C++11 capable	GCC, Clang, MSVC 2015+, Apple Clang
Disk	~500MB	Source + build artifacts

Dependencies

System Packages

`cmake` >= 2.8.12
C++ compiler (g++, clang++, or MSVC)
`git` (for cloning submodules)
`protobuf` (optional, for onnx2ncnn tool only)

Python Packages (for Python bindings only)

`python` >= 3.5
`numpy`
`tqdm`
`requests`
`portalocker`
`opencv-python`
`pybind11` (bundled as submodule)

Credentials

No credentials required for building ncnn from source.

Quick Install

# Clone with submodules
git clone https://github.com/Tencent/ncnn.git
cd ncnn
git submodule update --init

# Basic CPU-only build
mkdir build && cd build
cmake -DCMAKE_BUILD_TYPE=Release ..
make -j$(nproc)
make install

# Python bindings (optional)
cd /path/to/ncnn
pip install numpy tqdm requests portalocker opencv-python
python setup.py install

Code Evidence

CMake minimum version from `CMakeLists.txt:25`:

cmake_minimum_required(VERSION 2.8.12...3.10)

C++11 standard set for Python bindings in `python/CMakeLists.txt:8-9`:

set(CMAKE_CXX_STANDARD 11)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

Python package requirements from `setup.py:184`:

requirements = ["numpy", "tqdm", "requests", "portalocker", "opencv-python"]

SIMD detection auto-configuration in `src/CMakeLists.txt` (representative):

# ARM NEON, x86 SSE2/AVX/AVX2/AVX512, RISC-V RVV, MIPS MSA
# are all auto-detected and optional — no hard requirements

Common Errors

Error Message	Cause	Solution
`undefined reference to '__kmpc_XYZ'`	OpenMP linking issue on Android	Use Clang instead of GCC; check NDK_TOOLCHAIN_VERSION
`crash with '__kmp_abort_process'`	Multiple shared libs with OpenMP linked	Use `-fstatic-openmp -fopenmp` link flags (NDK >= 21)
`dlopen failed: library 'libomp.so' not found`	Dynamic OpenMP not available on Android	Use `-fstatic-openmp -fopenmp` link flags
`protobuf version conflict`	System protobuf conflicts with bundled	Use `-DNCNN_SYSTEM_GLSLANG=ON` or resolve protobuf versions

Compatibility Notes

Windows: Requires CMake 3.15+ for proper MSVC Runtime Library control. Defines `NOMINMAX` to avoid Windows macro conflicts.
Android: Disables RTTI and exceptions by default. NDK-21+ recommended for OpenMP. NDK-23+ needs `-mno-outline-atomics`.
macOS/iOS: Supports bitcode and ARC options via environment variables.
WebAssembly: Requires `-msimd128` instead of SSE2. Initial memory set to 256MB.
SIMD: All instruction set extensions (SSE2, AVX, NEON, RVV, etc.) are optional and auto-detected at compile time.

Related Pages

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment