MLX 安装与源码构建完全指南Apple silicon、CUDA 与 Linux CPU 三条部署路径详解【免费下载链接】mlxMLX: An array framework for Apple silicon项目地址: https://gitcode.com/GitHub_Trending/ml/mlxMLX 是面向 Apple silicon 的类 NumPy 数组框架其 Python API 与 NumPy 高度一致并同时提供功能完整的 C API。本文基于仓库中的官方安装文档docs/src/install.rst展开系统梳理三种主流安装路径——macOS 上的 PyPI 一键安装、Linux 上的 CUDA/CPU 后端安装、以及 Python/C 双 API 的源码编译——并结合仓库内 setup.py、CMakeLists.txt 等构建源码说明每个选项背后的真实行为。读完本文你将能针对自己的硬件与开发场景选择并落地一条最合适的 MLX 安装或构建方案并能独立排查安装过程中最常见的环境问题。一、安装场景与前置要求总览MLX 的安装方式随目标平台与后端而不同。当前仓库版本号见 mlx/version.h为 0.32.x 系列共支持三种典型的安装形态场景安装命令目标平台核心前置条件Apple silicon标准pip install mlxmacOSApple silicon、原生 Python 3.10、macOS 14.0NVIDIA GPUCUDA 12pip install mlx[cuda12]Linux架构 SM 7.5、驱动 550.54.14、CUDA toolkit 12.0、glibc 2.35、Python 3.10NVIDIA GPUCUDA 13pip install mlx[cuda13]Linux架构 SM 7.5、驱动 580 或相应 CUDA 兼容包、glibc 2.35、Python 3.10CPU-onlypip install mlx[cpu]Linuxglibc 2.35、Python 3.10需要特别强调的是MLX 仅支持运行于 macOS 14.0 及更高版本的设备上GPU 后端基于 Apple 的 Metal 框架源码中 macOS SDK 版本低于 14.0 时构建会直接报错详见下文源码分析。因此如果你的 macOS 版本低于 14.0无论采用哪种安装方式都无法获得可用的 MLX。二、通过 PyPI 安装 Python 版本2.1 Apple silicon 上的标准安装在 Apple silicon 电脑上使用 MLX 只需要一条命令pip install mlx执行该命令前系统必须满足以下三个条件使用 Apple siliconM 系列芯片设备使用原生Python版本 3.10setup.py中通过python_requires3.10强制约束见 setup.pymacOS 14.0。这里的原生 Python是很多新手踩坑的根源如果你是在 Rosetta 转译的 x86_64 环境中运行 Pythonpip 将无法找到匹配的 wheel。判断方法见下文 2.4 节。2.2 CUDA 后端安装LinuxMLX 提供独立的 CUDA 后端包安装命令为pip install mlx[cuda12]PyPI 上 CUDA 包的安装条件包括NVIDIA 架构 SM 7.5即 Volta 及之后NVIDIA 驱动 550.54.14CUDA toolkit 12.0带 glibc 2.35 的 Linux 发行版Python 3.10。若使用 CUDA 13则执行pip install mlx[cuda13]CUDA 13 包要求 NVIDIA 驱动 580或安装合适的 CUDA compatibility 包。从源码看setup.py 将这些 extra 映射到独立的后端子包mlx[cuda12]实际拉取mlx-cuda-12mlx[cuda13]实际拉取mlx-cuda-13并且这些后端包会继续依赖对应的 NVIDIA 运行时库如nvidia-cudnn-cu129.*、nvidia-nccl-cu12、nvidia-cublas-cu1212.9.*、nvidia-cufft-cu1211.4.*、nvidia-cuda-nvrtc-cu1212.9.*、nvidia-cusolver-cu1211.7.*CUDA 13 侧则对应nvidia-cublas13.*等见 setup.py。这意味着 pip 会替你打理好 cuDNN、cuBLAS、NCCL 等 CUDA 依赖无需手工安装全部 toolkit 组件。2.3 CPU-only 安装Linux不依赖 GPU 的纯 CPU 版本同样发布在 PyPI 上pip install mlx[cpu]其安装条件仅两条带 glibc 2.35 的 Linux 发行版Python 3.10。从 setup.py 可以看到mlx[cpu]实际安装的是名为mlx-cpu的后端包。这种前端包 后端包的拆分机制在 setup.py 的注释中有明确说明前端包名为mlx负责 Python API 与平台/ABI 标签而后端包mlx-metal、mlx-cuda-12、mlx-cuda-13、mlx-cpu携带各自的二进制实现由前端包按平台环境声明依赖。2.4 常见问题pip 找不到匹配的发行版系统与 Python 版本都在要求范围内但 pip 依然提示找不到匹配的 distribution。最可能的原因是使用了非原生 Python。在终端执行python -c import platform; print(platform.processor())输出应为arm。如果输出是i386而你用的是 M 系列机器说明当前 Python 运行在 x86 转译层之下。解决办法是切换为原生 Python例如通过 Conda 创建一个 arm64 架构的 Python 环境后再安装。切换到原生环境后pip 才能命中 Apple silicon 专用的 wheel。三、从源码构建 MLX当需要最新特性、自定义构建选项或目标平台不在 PyPI 预编译包覆盖范围内时可以选择从源码构建。MLX 的 Python API 与 C API 均支持源码构建。3.1 构建前置要求开始构建前请确保环境满足libblas-dev、liblapack-dev、liblapacke-devLinux 上需要支持 C20 的 C 编译器如 Clang 15.0。仓库顶层 CMakeLists.txt 通过CMAKE_CXX_STANDARD 20强制启用 C20 标准CMake 3.25 或更高版本以及make。顶层 CMakeLists.txt 声明了cmake_minimum_required(VERSION 3.25)pyproject.toml 的构建依赖中也要求cmake3.25Xcode 15.0且 macOS SDK 14.0。重要提示请确保 shell 环境是原生arm而非通过 Rosetta 运行的x86。若uname -p输出为x86请先参照本文第六节的排查步骤处理否则构建会在 CMake 配置阶段直接失败。源码中对这一约束有硬性检查顶层 CMakeLists.txt 在 Darwin 平台上检测到x86_64处理器时若未显式设置MLX_ENABLE_X64_MAC会直接报FATAL_ERRORBuilding for x86_64 on macOS is not supported.。3.2 构建 Python API首先克隆仓库git clone https://gitcode.com/GitHub_Trending/ml/mlx.git mlx cd mlx然后使用 pip 直接构建并安装pip install .如果是开发者模式需要安装开发依赖并使用可编辑安装pip install -e .[dev]其中[dev]extra 在 setup.py 中定义为ml_dtypes、numpy2、pre-commit、torch2.9、typing_extensions等开发用依赖。开发依赖就绪后可以用更快的方式做增量构建python setup.py build_ext --inplace该命令走的是 setup.py 中自定义的CMakeBuild构建流程它会自动向 CMake 传递-DMLX_BUILD_PYTHON_BINDINGSON、-DBUILD_SHARED_LIBSON、-DMLX_BUILD_TESTSOFF等参数并以-j{os.cpu_count()}进行并行编译同时会读取环境变量CMAKE_ARGS并追加为 CMake 参数这正是下文 CUDA 构建中CMAKE_ARGS-DMLX_BUILD_CUDAON能生效的原因见 setup.py。此外build_ext在 inplace 模式下还会将mlx.metallib等产物复制到位并生成类型存根type stubs。运行 Python 测试python python/tests/run.py该入口文件位于 python/tests/run.py它基于unittest的 test discovery 机制扫描python/tests目录下的全部测试用例如test_array.py、test_autograd.py、test_ops.py、test_compile.py等并统一通过MLXTestRunner执行。3.3 构建 C APIMLX 的 C 库目前必须从源码构建和安装。同样先克隆仓库git clone https://gitcode.com/GitHub_Trending/ml/mlx.git mlx cd mlx创建构建目录并执行 CMake 与 makemkdir -p build cd build cmake .. make -j运行 C 测试make test测试二进制由 tests/CMakeLists.txt 定义基于 doctest 框架聚合了array_tests.cpp、ops_tests.cpp、autograd_tests.cpp、compile_tests.cpp、linalg_tests.cpp等数十个测试源文件启用 GPU 后端时还会加入gpu_tests.cpp、residency_tests.cpp。安装到系统make install注意构建出的mlx.metallib文件必须与静态链接libmlx.a的可执行文件位于同一目录或者在构建时定义预处理常量METAL_PATH使其指向构建出的 Metal 库路径。这一约束在 Metal 后端构建脚本中有对应实现当未显式指定MLX_METAL_PATH时会默认指向构建目录下的kernels/并通过target_compile_definitions(... METAL_PATH${MLX_METAL_PATH}/mlx.metallib)注入宏见 mlx/backend/metal/CMakeLists.txt。3.4 CMake 构建选项详解安装文档给出了构建时最常用的一组 CMake 选项及其默认值OptionDefaultMLX_BUILD_TESTSONMLX_BUILD_EXAMPLESOFFMLX_BUILD_BENCHMARKSOFFMLX_BUILD_METALONMLX_BUILD_CPUONMLX_BUILD_PYTHON_BINDINGSOFFMLX_METAL_DEBUGOFFMLX_BUILD_SAFETENSORSONMLX_BUILD_GGUFONMLX_METAL_JITOFF这些选项在顶层 CMakeLists.txt 中均有对应的option()声明。结合源码可以更准确地理解它们的作用MLX_BUILD_METAL控制 MetalmacOS GPU后端。开启时 CMake 会查找 Metal/Foundation/QuartzCore 框架并通过xcrun -sdk macosx --show-sdk-version探测 macOS SDK若 SDK 14.0 则直接报错见 CMakeLists.txt。关闭时改用no_metal.cpp占位见 mlx/CMakeLists.txt。MLX_BUILD_CPU控制 CPU 后端。macOS 上优先链接 Apple Accelerate 框架Linux 上则通过find_package(LAPACK/BLAS REQUIRED)强制要求系统安装 BLAS/LAPACK见 CMakeLists.txt。MLX_BUILD_SAFETENSORS/MLX_BUILD_GGUF控制 safetensors 与 GGUF 模型格式的读写支持对应 mlx/io 目录下的safetensors.cpp与gguf.cpp等实现。MLX_METAL_JITMetal 内核的 JIT 编译开关对二进制体积影响显著详见 3.5 节。MLX_METAL_DEBUG开启 Metal 调试工作流等价于源码中的MLX_METAL_DEBUG编译宏见 CMakeLists.txt。此外顶层 CMakeLists 中还暴露了文档表格之外的更多选项按需使用选项默认说明MLX_BUILD_CUDAOFF构建 CUDA 后端开启时会enable_language(CUDA)并强制find_package(CUDAToolkit REQUIRED)与find_package(CUDNN REQUIRED)见 CMakeLists.txtMLX_ENABLE_X64_MACOFF允许在 x86_64 macOS 上构建官方不保证支持MLX_BUILD_PYTHON_STUBSON生成 Python 类型存根MLX_USE_CCACHEON编译缓存加速找到 ccache 时自动启用MLX_EXPORT_ALL_SYMBOLSOFF导出库的全部符号BUILD_SHARED_LIBSOFF以动态库方式构建USE_ASAN / USE_UBSAN / USE_TSANOFF开启对应 SanitizerASan 与 TSan 互斥TSan 不支持 macOS3.5 二进制体积最小化若需要产出更小的二进制可组合使用 CMake 标志CMAKE_BUILD_TYPEMinSizeRel与BUILD_SHARED_LIBSON。MLX 的 CMake 构建还提供了若干进一步瘦身的选项。例如如果不需要 CPU 后端也不使用 safetensors 与 GGUF可以这样配置cmake .. \ -DCMAKE_BUILD_TYPEMinSizeRel \ -DBUILD_SHARED_LIBSON \ -DMLX_BUILD_CPUOFF \ -DMLX_BUILD_SAFETENSORSOFF \ -DMLX_BUILD_GGUFOFF \ -DMLX_METAL_JITON其中MLX_METAL_JIT标志的作用是最小化 MLX Metal 库内含预编译 GPU kernel的体积开启后内核不再预编译进mlx.metallib而是在每台机器上首次使用时由运行时编译从而大幅缩减 Metal 库体积。其代价是冷启动开销——首次使用某内核时编译耗时从几百毫秒到几秒不等取决于具体应用内核一旦编译完成即被系统缓存且Metal kernel 缓存跨重启持久有效。对应的实现细节可见 mlx/backend/metal/CMakeLists.txtMLX_METAL_JITON时编译jit_kernels.cpp并对 arange、copy、unary、binary、gemm、conv、attention 等内核逐一执行make_jit_source预处理关闭时则退化为nojit_kernels.cpp。多 Xcode 并存提示如果机器上安装了多个 Xcode并希望指定某一个进行构建可在构建前设置环境变量export DEVELOPER_DIR/path/to/Xcode.app/Contents/Developer/并可用以下命令确认构建将使用的 macOS SDK 版本xcrun -sdk macosx --show-sdk-version3.6 在 Linux 上构建CPU onlyLinux 上源码构建 CPU 版需要先安装 BLAS 与 LAPACK 头文件。以 Ubuntu 为例apt-get update -y apt-get install libblas-dev liblapack-dev liblapacke-dev -y安装完成后按上文构建 Python API或构建 C API的步骤继续即可。从源码看Linux 上MLX_BUILD_METAL会被自动置为 OFF见 CMakeLists.txt因此默认走 CPU 后端。3.7 在 Linux 上构建 CUDA 版本Linux 上源码构建 CUDA 版需要安装 BLAS/LAPACK 头文件以及 CUDA toolkit。以 Ubuntu 为例wget https://developer.download.nvidia.com/compute/cuda/repos/ubuntu2204/x86_64/cuda-keyring_1.1-1_all.deb dpkg -i cuda-keyring_1.1-1_all.deb apt-get update -y apt-get -y install cuda-toolkit-12-9 apt-get install libblas-dev liblapack-dev liblapacke-dev libcudnn9-dev-cuda-12 -y构建 Python API 或 C API 时必须显式传入 cmake 标志MLX_BUILD_CUDAON。构建 Python API 的命令为CMAKE_ARGS-DMLX_BUILD_CUDAON pip install -e .[dev]构建 C 包mkdir -p build cd build cmake .. -DMLX_BUILD_CUDAON make -j关于 CUDA 后端有几个源码层面的细节值得了解未显式指定MLX_CUDA_ARCHITECTURES时构建会调用__nvcc_device_query探测本机 GPU 架构并据此编译见 mlx/backend/cuda/CMakeLists.txtPyPI 官方后端包则覆盖75-real/80-real/120a-real/120-virtual等架构Linux 额外加入90a-real/100a-real/121a-real见 setup.py。CUDA 后端依赖大量 NVIDIA 组件cuBLASLt、cuFFT、cuSOLVER、NVRTC、cuDNN frontend以及固定版本的 CUTLASSv4.4.2、CCCLv3.1.3与 NVTXv3.1.1这些依赖均由 CMake 的FetchContent自动拉取见 mlx/backend/cuda/CMakeLists.txt因此源码构建 CUDA 版通常需要联网。CUDA toolkit 13.1 在构建时会被显式拒绝见 CMakeLists.txt。四、构建产物与库集成源码安装完成后MLX 提供标准的 CMake 包配置文件由 mlx.pc.in 模板生成。安装后的MLXConfig.cmake会导出MLX_FOUND、MLX_INCLUDE_DIRS、MLX_LIBRARIES、MLX_CXX_FLAGS等变量并声明MLX_BUILD_METAL、MLX_BUILD_ACCELERATE、MLX_BUILD_CUDA等构建特性标志若 MLX 以 Metal 后端构建还会自动把 metal_cpp 及对应 Metal 版本metal_3_0 / metal_3_1的内核头目录加入 include 路径见 mlx.pc.in。在你的 CMake 工程中通过find_package(MLX)即可找到并链接 MLXfind_package(MLX REQUIRED) target_link_libraries(your_target PRIVATE mlx)结合 C 侧 API参考 mlx/api.h 与 mlx/mlx.h即可在自定义 C 程序中调用 MLX 的数组运算能力。仓库 examples/cpp 与 examples/cmake_project 提供了可直接参考的 C 示例工程含 CMakeLists 配置。五、安装与构建后的验证安装完成后可通过以下方式快速验证环境python -c import mlx; print(mlx.__version__)Python 侧的功能验证可运行官方测试套件python python/tests/run.pyC 侧则使用 doctest 驱动的一体化测试程序构建目录内make test关于测试的更多细节Python 测试覆盖数组、自动微分、编译、量化、FFT、linalg、随机数、图变换等模块见 python/tests 目录下的test_*.py文件C 测试则聚合了运算、BLAS、调度器、vmap、内存驻留等单元测试见 tests/CMakeLists.txt。若仅做开发验证也可参考仓库 benchmarks/python 中的各类基准脚本或 examples/python 中的线性回归、逻辑回归等入门示例。六、常见构建问题排查6.1 Metal not found构建时出现如下错误error: unable to find utility metal, not a developer tool or in PATH处理步骤确认已安装 Xcodexcode-select --install设置激活的开发者目录sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer该错误的本质是 CMake 在配置阶段找不到 Metal 工具链。从源码看macOS 上开启MLX_BUILD_METAL后CMake 会依次探测 Metal 框架、macOS 版本sw_vers -productVersion、SDK 版本xcrun -sdk macosx --show-sdk-version低于 14.0 会FATAL_ERROR以及 Metal 版本通过xcrun -sdk macosx metal -E预处理__METAL_VERSION__任何一个环节失败都会导致配置终止见 CMakeLists.txt。6.2 Shell 以 x86 模式运行Rosetta如果uname -p输出为x86说明你的 shell 正以 Rosetta 转译的 x86 模式运行而非原生模式。修复方法在 Finder 中找到对应应用iTerm 位于/ApplicationsTerminal 位于/Applications/Utilities右键点击并选择显示简介Get Info取消勾选使用 Rosetta 打开关闭简介窗口后重启终端。随后验证终端已原生运行$ uname -p arm同时检查 cmake 是否使用正确的架构$ cmake --system-information | grep CMAKE_HOST_SYSTEM_PROCESSOR CMAKE_HOST_SYSTEM_PROCESSOR arm64如果输出为x86_64尝试重新安装 cmake。如果输出已是arm64但构建仍报 Building for x86_64 on macOS is not supported. 错误请清空构建缓存后重试rm -rf build/在源码层面该报错来自顶层 CMakeLists.txt 对 Darwin x86_64 组合的硬性检查。七、安装路径选择建议最后根据使用场景给出快速决策建议macOSApple silicon上的日常使用与模型训练直接pip install mlx无需源码构建注意使用原生 arm64 Python。Linux 上使用 NVIDIA GPU优先pip install mlx[cuda12]或pip install mlx[cuda13]让 pip 自动处理 cuDNN/NCCL/cuBLAS 等依赖需要自定义架构或依赖时再走源码构建-DMLX_BUILD_CUDAON。Linux 纯 CPU 推理/调试pip install mlx[cpu]最省事源码构建需先安装libblas-dev、liblapack-dev、liblapacke-dev。C 开发或深度定制内核、后端、二进制体积走源码构建结合MLX_METAL_JIT、MLX_BUILD_CPU、MLX_BUILD_SAFETENSORS等选项按需裁剪。无论选择哪条路径只要前置条件满足macOS 14.0 或 Linux glibc 2.35、Python 3.10、原生架构环境MLX 的安装与构建都是直接可复现的。【免费下载链接】mlxMLX: An array framework for Apple silicon项目地址: https://gitcode.com/GitHub_Trending/ml/mlx创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 MLX 安装与源码构建完全指南：Apple silicon、CUDA 与 Linux CPU 三条部署路径详解
MLX 安装与源码构建完全指南Apple silicon、CUDA 与 Linux CPU 三条部署路径详解【免费下载链接】mlxMLX: An array framework for Apple silicon项目地址: https://gitcode.com/GitHub_Trending/ml/mlxMLX 是面向 Apple silicon 的类 NumPy 数组框架其 Python API 与 NumPy 高度一致并同时提供功能完整的 C API。本文基于仓库中的官方安装文档docs/src/install.rst展开系统梳理三种主流安装路径——macOS 上的 PyPI 一键安装、Linux 上的 CUDA/CPU 后端安装、以及 Python/C 双 API 的源码编译——并结合仓库内 setup.py、CMakeLists.txt 等构建源码说明每个选项背后的真实行为。读完本文你将能针对自己的硬件与开发场景选择并落地一条最合适的 MLX 安装或构建方案并能独立排查安装过程中最常见的环境问题。一、安装场景与前置要求总览MLX 的安装方式随目标平台与后端而不同。当前仓库版本号见 mlx/version.h为 0.32.x 系列共支持三种典型的安装形态场景安装命令目标平台核心前置条件Apple silicon标准pip install mlxmacOSApple silicon、原生 Python 3.10、macOS 14.0NVIDIA GPUCUDA 12pip install mlx[cuda12]Linux架构 SM 7.5、驱动 550.54.14、CUDA toolkit 12.0、glibc 2.35、Python 3.10NVIDIA GPUCUDA 13pip install mlx[cuda13]Linux架构 SM 7.5、驱动 580 或相应 CUDA 兼容包、glibc 2.35、Python 3.10CPU-onlypip install mlx[cpu]Linuxglibc 2.35、Python 3.10需要特别强调的是MLX 仅支持运行于 macOS 14.0 及更高版本的设备上GPU 后端基于 Apple 的 Metal 框架源码中 macOS SDK 版本低于 14.0 时构建会直接报错详见下文源码分析。因此如果你的 macOS 版本低于 14.0无论采用哪种安装方式都无法获得可用的 MLX。二、通过 PyPI 安装 Python 版本2.1 Apple silicon 上的标准安装在 Apple silicon 电脑上使用 MLX 只需要一条命令pip install mlx执行该命令前系统必须满足以下三个条件使用 Apple siliconM 系列芯片设备使用原生Python版本 3.10setup.py中通过python_requires3.10强制约束见 setup.pymacOS 14.0。这里的原生 Python是很多新手踩坑的根源如果你是在 Rosetta 转译的 x86_64 环境中运行 Pythonpip 将无法找到匹配的 wheel。判断方法见下文 2.4 节。2.2 CUDA 后端安装LinuxMLX 提供独立的 CUDA 后端包安装命令为pip install mlx[cuda12]PyPI 上 CUDA 包的安装条件包括NVIDIA 架构 SM 7.5即 Volta 及之后NVIDIA 驱动 550.54.14CUDA toolkit 12.0带 glibc 2.35 的 Linux 发行版Python 3.10。若使用 CUDA 13则执行pip install mlx[cuda13]CUDA 13 包要求 NVIDIA 驱动 580或安装合适的 CUDA compatibility 包。从源码看setup.py 将这些 extra 映射到独立的后端子包mlx[cuda12]实际拉取mlx-cuda-12mlx[cuda13]实际拉取mlx-cuda-13并且这些后端包会继续依赖对应的 NVIDIA 运行时库如nvidia-cudnn-cu129.*、nvidia-nccl-cu12、nvidia-cublas-cu1212.9.*、nvidia-cufft-cu1211.4.*、nvidia-cuda-nvrtc-cu1212.9.*、nvidia-cusolver-cu1211.7.*CUDA 13 侧则对应nvidia-cublas13.*等见 setup.py。这意味着 pip 会替你打理好 cuDNN、cuBLAS、NCCL 等 CUDA 依赖无需手工安装全部 toolkit 组件。2.3 CPU-only 安装Linux不依赖 GPU 的纯 CPU 版本同样发布在 PyPI 上pip install mlx[cpu]其安装条件仅两条带 glibc 2.35 的 Linux 发行版Python 3.10。从 setup.py 可以看到mlx[cpu]实际安装的是名为mlx-cpu的后端包。这种前端包 后端包的拆分机制在 setup.py 的注释中有明确说明前端包名为mlx负责 Python API 与平台/ABI 标签而后端包mlx-metal、mlx-cuda-12、mlx-cuda-13、mlx-cpu携带各自的二进制实现由前端包按平台环境声明依赖。2.4 常见问题pip 找不到匹配的发行版系统与 Python 版本都在要求范围内但 pip 依然提示找不到匹配的 distribution。最可能的原因是使用了非原生 Python。在终端执行python -c import platform; print(platform.processor())输出应为arm。如果输出是i386而你用的是 M 系列机器说明当前 Python 运行在 x86 转译层之下。解决办法是切换为原生 Python例如通过 Conda 创建一个 arm64 架构的 Python 环境后再安装。切换到原生环境后pip 才能命中 Apple silicon 专用的 wheel。三、从源码构建 MLX当需要最新特性、自定义构建选项或目标平台不在 PyPI 预编译包覆盖范围内时可以选择从源码构建。MLX 的 Python API 与 C API 均支持源码构建。3.1 构建前置要求开始构建前请确保环境满足libblas-dev、liblapack-dev、liblapacke-devLinux 上需要支持 C20 的 C 编译器如 Clang 15.0。仓库顶层 CMakeLists.txt 通过CMAKE_CXX_STANDARD 20强制启用 C20 标准CMake 3.25 或更高版本以及make。顶层 CMakeLists.txt 声明了cmake_minimum_required(VERSION 3.25)pyproject.toml 的构建依赖中也要求cmake3.25Xcode 15.0且 macOS SDK 14.0。重要提示请确保 shell 环境是原生arm而非通过 Rosetta 运行的x86。若uname -p输出为x86请先参照本文第六节的排查步骤处理否则构建会在 CMake 配置阶段直接失败。源码中对这一约束有硬性检查顶层 CMakeLists.txt 在 Darwin 平台上检测到x86_64处理器时若未显式设置MLX_ENABLE_X64_MAC会直接报FATAL_ERRORBuilding for x86_64 on macOS is not supported.。3.2 构建 Python API首先克隆仓库git clone https://gitcode.com/GitHub_Trending/ml/mlx.git mlx cd mlx然后使用 pip 直接构建并安装pip install .如果是开发者模式需要安装开发依赖并使用可编辑安装pip install -e .[dev]其中[dev]extra 在 setup.py 中定义为ml_dtypes、numpy2、pre-commit、torch2.9、typing_extensions等开发用依赖。开发依赖就绪后可以用更快的方式做增量构建python setup.py build_ext --inplace该命令走的是 setup.py 中自定义的CMakeBuild构建流程它会自动向 CMake 传递-DMLX_BUILD_PYTHON_BINDINGSON、-DBUILD_SHARED_LIBSON、-DMLX_BUILD_TESTSOFF等参数并以-j{os.cpu_count()}进行并行编译同时会读取环境变量CMAKE_ARGS并追加为 CMake 参数这正是下文 CUDA 构建中CMAKE_ARGS-DMLX_BUILD_CUDAON能生效的原因见 setup.py。此外build_ext在 inplace 模式下还会将mlx.metallib等产物复制到位并生成类型存根type stubs。运行 Python 测试python python/tests/run.py该入口文件位于 python/tests/run.py它基于unittest的 test discovery 机制扫描python/tests目录下的全部测试用例如test_array.py、test_autograd.py、test_ops.py、test_compile.py等并统一通过MLXTestRunner执行。3.3 构建 C APIMLX 的 C 库目前必须从源码构建和安装。同样先克隆仓库git clone https://gitcode.com/GitHub_Trending/ml/mlx.git mlx cd mlx创建构建目录并执行 CMake 与 makemkdir -p build cd build cmake .. make -j运行 C 测试make test测试二进制由 tests/CMakeLists.txt 定义基于 doctest 框架聚合了array_tests.cpp、ops_tests.cpp、autograd_tests.cpp、compile_tests.cpp、linalg_tests.cpp等数十个测试源文件启用 GPU 后端时还会加入gpu_tests.cpp、residency_tests.cpp。安装到系统make install注意构建出的mlx.metallib文件必须与静态链接libmlx.a的可执行文件位于同一目录或者在构建时定义预处理常量METAL_PATH使其指向构建出的 Metal 库路径。这一约束在 Metal 后端构建脚本中有对应实现当未显式指定MLX_METAL_PATH时会默认指向构建目录下的kernels/并通过target_compile_definitions(... METAL_PATH${MLX_METAL_PATH}/mlx.metallib)注入宏见 mlx/backend/metal/CMakeLists.txt。3.4 CMake 构建选项详解安装文档给出了构建时最常用的一组 CMake 选项及其默认值OptionDefaultMLX_BUILD_TESTSONMLX_BUILD_EXAMPLESOFFMLX_BUILD_BENCHMARKSOFFMLX_BUILD_METALONMLX_BUILD_CPUONMLX_BUILD_PYTHON_BINDINGSOFFMLX_METAL_DEBUGOFFMLX_BUILD_SAFETENSORSONMLX_BUILD_GGUFONMLX_METAL_JITOFF这些选项在顶层 CMakeLists.txt 中均有对应的option()声明。结合源码可以更准确地理解它们的作用MLX_BUILD_METAL控制 MetalmacOS GPU后端。开启时 CMake 会查找 Metal/Foundation/QuartzCore 框架并通过xcrun -sdk macosx --show-sdk-version探测 macOS SDK若 SDK 14.0 则直接报错见 CMakeLists.txt。关闭时改用no_metal.cpp占位见 mlx/CMakeLists.txt。MLX_BUILD_CPU控制 CPU 后端。macOS 上优先链接 Apple Accelerate 框架Linux 上则通过find_package(LAPACK/BLAS REQUIRED)强制要求系统安装 BLAS/LAPACK见 CMakeLists.txt。MLX_BUILD_SAFETENSORS/MLX_BUILD_GGUF控制 safetensors 与 GGUF 模型格式的读写支持对应 mlx/io 目录下的safetensors.cpp与gguf.cpp等实现。MLX_METAL_JITMetal 内核的 JIT 编译开关对二进制体积影响显著详见 3.5 节。MLX_METAL_DEBUG开启 Metal 调试工作流等价于源码中的MLX_METAL_DEBUG编译宏见 CMakeLists.txt。此外顶层 CMakeLists 中还暴露了文档表格之外的更多选项按需使用选项默认说明MLX_BUILD_CUDAOFF构建 CUDA 后端开启时会enable_language(CUDA)并强制find_package(CUDAToolkit REQUIRED)与find_package(CUDNN REQUIRED)见 CMakeLists.txtMLX_ENABLE_X64_MACOFF允许在 x86_64 macOS 上构建官方不保证支持MLX_BUILD_PYTHON_STUBSON生成 Python 类型存根MLX_USE_CCACHEON编译缓存加速找到 ccache 时自动启用MLX_EXPORT_ALL_SYMBOLSOFF导出库的全部符号BUILD_SHARED_LIBSOFF以动态库方式构建USE_ASAN / USE_UBSAN / USE_TSANOFF开启对应 SanitizerASan 与 TSan 互斥TSan 不支持 macOS3.5 二进制体积最小化若需要产出更小的二进制可组合使用 CMake 标志CMAKE_BUILD_TYPEMinSizeRel与BUILD_SHARED_LIBSON。MLX 的 CMake 构建还提供了若干进一步瘦身的选项。例如如果不需要 CPU 后端也不使用 safetensors 与 GGUF可以这样配置cmake .. \ -DCMAKE_BUILD_TYPEMinSizeRel \ -DBUILD_SHARED_LIBSON \ -DMLX_BUILD_CPUOFF \ -DMLX_BUILD_SAFETENSORSOFF \ -DMLX_BUILD_GGUFOFF \ -DMLX_METAL_JITON其中MLX_METAL_JIT标志的作用是最小化 MLX Metal 库内含预编译 GPU kernel的体积开启后内核不再预编译进mlx.metallib而是在每台机器上首次使用时由运行时编译从而大幅缩减 Metal 库体积。其代价是冷启动开销——首次使用某内核时编译耗时从几百毫秒到几秒不等取决于具体应用内核一旦编译完成即被系统缓存且Metal kernel 缓存跨重启持久有效。对应的实现细节可见 mlx/backend/metal/CMakeLists.txtMLX_METAL_JITON时编译jit_kernels.cpp并对 arange、copy、unary、binary、gemm、conv、attention 等内核逐一执行make_jit_source预处理关闭时则退化为nojit_kernels.cpp。多 Xcode 并存提示如果机器上安装了多个 Xcode并希望指定某一个进行构建可在构建前设置环境变量export DEVELOPER_DIR/path/to/Xcode.app/Contents/Developer/并可用以下命令确认构建将使用的 macOS SDK 版本xcrun -sdk macosx --show-sdk-version3.6 在 Linux 上构建CPU onlyLinux 上源码构建 CPU 版需要先安装 BLAS 与 LAPACK 头文件。以 Ubuntu 为例apt-get update -y apt-get install libblas-dev liblapack-dev liblapacke-dev -y安装完成后按上文构建 Python API或构建 C API的步骤继续即可。从源码看Linux 上MLX_BUILD_METAL会被自动置为 OFF见 CMakeLists.txt因此默认走 CPU 后端。3.7 在 Linux 上构建 CUDA 版本Linux 上源码构建 CUDA 版需要安装 BLAS/LAPACK 头文件以及 CUDA toolkit。以 Ubuntu 为例wget https://developer.download.nvidia.com/compute/cuda/repos/ubuntu2204/x86_64/cuda-keyring_1.1-1_all.deb dpkg -i cuda-keyring_1.1-1_all.deb apt-get update -y apt-get -y install cuda-toolkit-12-9 apt-get install libblas-dev liblapack-dev liblapacke-dev libcudnn9-dev-cuda-12 -y构建 Python API 或 C API 时必须显式传入 cmake 标志MLX_BUILD_CUDAON。构建 Python API 的命令为CMAKE_ARGS-DMLX_BUILD_CUDAON pip install -e .[dev]构建 C 包mkdir -p build cd build cmake .. -DMLX_BUILD_CUDAON make -j关于 CUDA 后端有几个源码层面的细节值得了解未显式指定MLX_CUDA_ARCHITECTURES时构建会调用__nvcc_device_query探测本机 GPU 架构并据此编译见 mlx/backend/cuda/CMakeLists.txtPyPI 官方后端包则覆盖75-real/80-real/120a-real/120-virtual等架构Linux 额外加入90a-real/100a-real/121a-real见 setup.py。CUDA 后端依赖大量 NVIDIA 组件cuBLASLt、cuFFT、cuSOLVER、NVRTC、cuDNN frontend以及固定版本的 CUTLASSv4.4.2、CCCLv3.1.3与 NVTXv3.1.1这些依赖均由 CMake 的FetchContent自动拉取见 mlx/backend/cuda/CMakeLists.txt因此源码构建 CUDA 版通常需要联网。CUDA toolkit 13.1 在构建时会被显式拒绝见 CMakeLists.txt。四、构建产物与库集成源码安装完成后MLX 提供标准的 CMake 包配置文件由 mlx.pc.in 模板生成。安装后的MLXConfig.cmake会导出MLX_FOUND、MLX_INCLUDE_DIRS、MLX_LIBRARIES、MLX_CXX_FLAGS等变量并声明MLX_BUILD_METAL、MLX_BUILD_ACCELERATE、MLX_BUILD_CUDA等构建特性标志若 MLX 以 Metal 后端构建还会自动把 metal_cpp 及对应 Metal 版本metal_3_0 / metal_3_1的内核头目录加入 include 路径见 mlx.pc.in。在你的 CMake 工程中通过find_package(MLX)即可找到并链接 MLXfind_package(MLX REQUIRED) target_link_libraries(your_target PRIVATE mlx)结合 C 侧 API参考 mlx/api.h 与 mlx/mlx.h即可在自定义 C 程序中调用 MLX 的数组运算能力。仓库 examples/cpp 与 examples/cmake_project 提供了可直接参考的 C 示例工程含 CMakeLists 配置。五、安装与构建后的验证安装完成后可通过以下方式快速验证环境python -c import mlx; print(mlx.__version__)Python 侧的功能验证可运行官方测试套件python python/tests/run.pyC 侧则使用 doctest 驱动的一体化测试程序构建目录内make test关于测试的更多细节Python 测试覆盖数组、自动微分、编译、量化、FFT、linalg、随机数、图变换等模块见 python/tests 目录下的test_*.py文件C 测试则聚合了运算、BLAS、调度器、vmap、内存驻留等单元测试见 tests/CMakeLists.txt。若仅做开发验证也可参考仓库 benchmarks/python 中的各类基准脚本或 examples/python 中的线性回归、逻辑回归等入门示例。六、常见构建问题排查6.1 Metal not found构建时出现如下错误error: unable to find utility metal, not a developer tool or in PATH处理步骤确认已安装 Xcodexcode-select --install设置激活的开发者目录sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer该错误的本质是 CMake 在配置阶段找不到 Metal 工具链。从源码看macOS 上开启MLX_BUILD_METAL后CMake 会依次探测 Metal 框架、macOS 版本sw_vers -productVersion、SDK 版本xcrun -sdk macosx --show-sdk-version低于 14.0 会FATAL_ERROR以及 Metal 版本通过xcrun -sdk macosx metal -E预处理__METAL_VERSION__任何一个环节失败都会导致配置终止见 CMakeLists.txt。6.2 Shell 以 x86 模式运行Rosetta如果uname -p输出为x86说明你的 shell 正以 Rosetta 转译的 x86 模式运行而非原生模式。修复方法在 Finder 中找到对应应用iTerm 位于/ApplicationsTerminal 位于/Applications/Utilities右键点击并选择显示简介Get Info取消勾选使用 Rosetta 打开关闭简介窗口后重启终端。随后验证终端已原生运行$ uname -p arm同时检查 cmake 是否使用正确的架构$ cmake --system-information | grep CMAKE_HOST_SYSTEM_PROCESSOR CMAKE_HOST_SYSTEM_PROCESSOR arm64如果输出为x86_64尝试重新安装 cmake。如果输出已是arm64但构建仍报 Building for x86_64 on macOS is not supported. 错误请清空构建缓存后重试rm -rf build/在源码层面该报错来自顶层 CMakeLists.txt 对 Darwin x86_64 组合的硬性检查。七、安装路径选择建议最后根据使用场景给出快速决策建议macOSApple silicon上的日常使用与模型训练直接pip install mlx无需源码构建注意使用原生 arm64 Python。Linux 上使用 NVIDIA GPU优先pip install mlx[cuda12]或pip install mlx[cuda13]让 pip 自动处理 cuDNN/NCCL/cuBLAS 等依赖需要自定义架构或依赖时再走源码构建-DMLX_BUILD_CUDAON。Linux 纯 CPU 推理/调试pip install mlx[cpu]最省事源码构建需先安装libblas-dev、liblapack-dev、liblapacke-dev。C 开发或深度定制内核、后端、二进制体积走源码构建结合MLX_METAL_JIT、MLX_BUILD_CPU、MLX_BUILD_SAFETENSORS等选项按需裁剪。无论选择哪条路径只要前置条件满足macOS 14.0 或 Linux glibc 2.35、Python 3.10、原生架构环境MLX 的安装与构建都是直接可复现的。【免费下载链接】mlxMLX: An array framework for Apple silicon项目地址: https://gitcode.com/GitHub_Trending/ml/mlx创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考