Environment:Alibaba MNN GPU Metal Environment

Field	Value
environment_name	GPU_Metal_Environment
environment_type	GPU Acceleration
repository	Alibaba_MNN
platform	macOS, iOS
source_file	CMakeLists.txt (L255, L83, L630-631), include/MNN/MNNForwardType.h (L24)
last_updated	2026-02-10 14:00 GMT

Overview

Apple Metal GPU acceleration environment for MNN on iOS and macOS. This environment provides GPU-accelerated neural network inference using Apple's Metal API, supporting both traditional Metal compute shaders and newer Metal4 tensor instructions for Apple Silicon.

Description

The Metal backend (MNN_FORWARD_METAL) offloads neural network operations to Apple GPUs via the Metal framework. It is the recommended GPU acceleration path for all Apple platforms. MNN includes optional support for Metal4 tensor instructions (MNN_METAL_TENSOR=ON by default), which leverage the matrix acceleration hardware present in Apple Silicon chips for improved performance on supported operations.

For iOS deployments, MNN should be built as a framework (MNN_AAPL_FMWK=ON) rather than a traditional static or dynamic library, enabling seamless integration with Xcode projects.

Usage

Use this environment when deploying MNN models on Apple devices -- iPhones, iPads, and Macs with Apple Silicon or discrete AMD GPUs. Typical use cases include on-device LLM inference, diffusion model generation, and real-time image processing on iOS/macOS applications.

System Requirements

Operating System: macOS 10.14+ or iOS 12.0+
GPU: Metal-capable GPU
- iPhone 8 or later (A11 Bionic and newer)
- iPad (5th generation) or later
- Mac with Apple Silicon (M1, M2, M3, M4 series) or discrete AMD GPU
Xcode: Xcode 11 or later (provides Metal framework, Metal compiler, and iOS/macOS SDK)
CMake: Version 3.6 or later
Metal4 tensor instructions: Require Apple Silicon M4 or A17 Pro or later (enabled by default via MNN_METAL_TENSOR=ON; gracefully degrades on older hardware)

Dependencies

Dependency	Required	Notes
Metal framework	Yes	Ships with macOS and iOS; no separate installation needed
Xcode	Yes	Provides the Metal compiler (`metallib`) and platform SDKs
CMake	Yes	Build system; must be 3.6 or later
MNN_AAPL_FMWK	Conditional	Set to ON for iOS framework builds; required for proper iOS app integration

Credentials

No credentials, API keys, or tokens are required for this environment. The Metal framework is included in Apple's operating systems.

Quick Install

# 1. Ensure Xcode and command-line tools are installed
xcode-select --install

# 2. Clone MNN repository
git clone https://github.com/alibaba/MNN.git
cd MNN

# --- macOS Desktop Build ---
mkdir build && cd build
cmake .. \
    -DMNN_METAL=ON \
    -DCMAKE_BUILD_TYPE=Release
make -j$(sysctl -n hw.ncpu)

# --- macOS Build with LLM Support ---
mkdir build_llm && cd build_llm
cmake .. \
    -DMNN_METAL=ON \
    -DMNN_BUILD_LLM=ON \
    -DMNN_LOW_MEMORY=ON \
    -DMNN_SUPPORT_TRANSFORMER_FUSE=ON \
    -DCMAKE_BUILD_TYPE=Release
make -j$(sysctl -n hw.ncpu)

# --- iOS Framework Build ---
mkdir build_ios && cd build_ios
cmake .. \
    -DCMAKE_BUILD_TYPE=Release \
    -DCMAKE_SYSTEM_NAME=iOS \
    -DMNN_METAL=ON \
    -DMNN_AAPL_FMWK=ON \
    -DMNN_BUILD_LLM=ON \
    -DMNN_LOW_MEMORY=ON \
    -DMNN_SUPPORT_TRANSFORMER_FUSE=ON \
    -DMNN_ARM82=ON
make -j$(sysctl -n hw.ncpu)

# --- iOS Build with Diffusion Support ---
mkdir build_ios_diffusion && cd build_ios_diffusion
cmake .. \
    -DCMAKE_BUILD_TYPE=Release \
    -DCMAKE_SYSTEM_NAME=iOS \
    -DMNN_METAL=ON \
    -DMNN_AAPL_FMWK=ON \
    -DMNN_BUILD_DIFFUSION=ON
make -j$(sysctl -n hw.ncpu)

Code Evidence

CMakeLists.txt (Line 255): Metal option

option(MNN_METAL "Enable Metal" OFF)

Metal is disabled by default and must be explicitly enabled with -DMNN_METAL=ON.

CMakeLists.txt (Line 83): Metal4 tensor instructions

option(MNN_METAL_TENSOR "Use Metal4 tensor instructions" ON)

Metal4 tensor instructions are enabled by default. These leverage the matrix acceleration hardware on newer Apple Silicon chips. The option can be set to OFF for compatibility with older Apple hardware or to debug performance issues.

CMakeLists.txt (Line 64): Framework build option

option(MNN_AAPL_FMWK "Build MNN.framework instead of traditional .a/.dylib" OFF)

For iOS app integration, MNN_AAPL_FMWK=ON builds MNN as an Apple framework (MNN.framework) instead of a standalone library.

CMakeLists.txt (Lines 630-631): Metal backend activation

if(MNN_METAL AND APPLE)
    target_compile_options(MNNCore PRIVATE -DMNN_METAL_ENABLED=1)

The Metal backend is only compiled when both MNN_METAL=ON and the target platform is Apple (APPLE is true). The MNN_METAL_ENABLED preprocessor definition is set to activate Metal code paths.

CMakeLists.txt (Line 44): OpenMP incompatibility

option(MNN_OPENMP "Use OpenMP's thread pool implementation. Does not work on iOS or Mac OS" OFF)

OpenMP is explicitly documented as incompatible with iOS and macOS. MNN's thread pool implementation should be used instead on Apple platforms.

MNNForwardType.h (Line 24): Forward type enum

/*Hand write metal*/
MNN_FORWARD_METAL = 1,

The Metal backend is identified by the forward type constant MNN_FORWARD_METAL = 1.

Common Errors

Error	Cause	Resolution
`Metal framework not found`	Building on non-Apple platform or Xcode not installed	Metal is Apple-only; install Xcode and ensure you are building on macOS
`MNN_AAPL_FMWK and MNN_SEP_BUILD can't coexist`	Both framework and separate build modes enabled simultaneously	The CMake script automatically turns off `MNN_SEP_BUILD` when `MNN_AAPL_FMWK=ON` (CMakeLists.txt:129-131). No action needed; this is a warning, not an error
Metal shader compilation errors	Xcode or Metal tools version too old for Metal4 tensor features	Update Xcode to the latest version; alternatively set `-DMNN_METAL_TENSOR=OFF` to disable Metal4 tensor instructions
OpenMP linking errors on macOS	`MNN_OPENMP=ON` set on Apple platform	Set `MNN_OPENMP=OFF` (the default); OpenMP is not supported on iOS or macOS
App Store rejection for non-framework build	iOS build not using framework packaging	Set `-DMNN_AAPL_FMWK=ON` for all iOS builds intended for App Store distribution

Compatibility Notes

iOS: Requires MNN_AAPL_FMWK=ON for framework builds suitable for iOS app integration. MNN_SEP_BUILD is automatically disabled when building as a framework (CMakeLists.txt:129-131).
OpenMP: Not supported on iOS or macOS. The CMake option documentation explicitly states this: "Does not work on iOS or Mac OS." Use MNN's built-in thread pool instead (MNN_USE_THREAD_POOL=ON).
Metal4 tensor instructions: Enabled by default (MNN_METAL_TENSOR=ON). These instructions are used at runtime only on supported hardware (Apple Silicon M4/A17 Pro+) and are ignored on older chips.
macOS: Both Apple Silicon and Intel Macs with discrete AMD GPUs are supported. Apple Silicon benefits from the Metal4 tensor path.
MNN_FORWARD_AUTO: On Apple platforms, MNN_FORWARD_AUTO will select the Metal backend if available, falling back to CPU otherwise.
CoreML alternative: For Neural Engine (ANE) acceleration on Apple Silicon, consider MNN_FORWARD_NN with CoreML (MNN_COREML=ON) as an alternative or complement to Metal.

Related Pages

Page Connections

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

Principle

Implementation

Heuristic

Environment