Build and Install

Build and Install#

Python Installation#

MLX is available on PyPI. All you have to do to use MLX with your own Apple silicon computer is

pip install mlx

To install from PyPI you must meet the following requirements:

  • Using an M series chip (Apple silicon)

  • Using a native Python >= 3.9

  • macOS >= 13.5

Note

MLX is only available on devices running macOS >= 13.5 It is highly recommended to use macOS 14 (Sonoma)

MLX is also available on conda-forge. To install MLX with conda do:

conda install conda-forge::mlx

Troubleshooting#

My OS and Python versions are in the required range but pip still does not find a matching distribution.

Probably you are using a non-native Python. The output of

python -c "import platform; print(platform.processor())"

should be arm. If it is i386 (and you have M series machine) then you are using a non-native Python. Switch your Python to a native Python. A good way to do this is with Conda.

Build from source#

Build Requirements#

  • A C++ compiler with C++17 support (e.g. Clang >= 5.0)

  • cmake – version 3.24 or later, and make

  • Xcode >= 15.0 and macOS SDK >= 14.0

Note

Ensure your shell environment is native arm, not x86 via Rosetta. If the output of uname -p is x86, see the troubleshooting section below.

Python API#

To build and install the MLX python library from source, first, clone MLX from its GitHub repo:

git clone [email protected]:ml-explore/mlx.git mlx && cd mlx

Then simply build and install MLX using pip:

CMAKE_BUILD_PARALLEL_LEVEL=8 pip install .

For developing, install the package with development dependencies, and use an editable install:

CMAKE_BUILD_PARALLEL_LEVEL=8 pip install -e ".[dev]"

Once the development dependencies are installed, you can build faster with:

CMAKE_BUILD_PARALLEL_LEVEL=8 python setup.py build_ext --inplace

Run the tests with:

python -m unittest discover python/tests

Optional: Install stubs to enable auto completions and type checking from your IDE:

python setup.py generate_stubs

C++ API#

Currently, MLX must be built and installed from source.

Similarly to the python library, to build and install the MLX C++ library start by cloning MLX from its GitHub repo:

git clone [email protected]:ml-explore/mlx.git mlx && cd mlx

Create a build directory and run CMake and make:

mkdir -p build && cd build
cmake .. && make -j

Run tests with:

make test

Install with:

make install

Note that the built mlx.metallib file should be either at the same directory as the executable statically linked to libmlx.a or the preprocessor constant METAL_PATH should be defined at build time and it should point to the path to the built metal library.

Build Options#

Option

Default

MLX_BUILD_TESTS

ON

MLX_BUILD_EXAMPLES

OFF

MLX_BUILD_BENCHMARKS

OFF

MLX_BUILD_METAL

ON

MLX_BUILD_CPU

ON

MLX_BUILD_PYTHON_BINDINGS

OFF

MLX_METAL_DEBUG

OFF

MLX_BUILD_SAFETENSORS

ON

MLX_BUILD_GGUF

ON

MLX_METAL_JIT

OFF

Note

If you have multiple Xcode installations and wish to use a specific one while building, you can do so by adding the following environment variable before building

export DEVELOPER_DIR="/path/to/Xcode.app/Contents/Developer/"

Further, you can use the following command to find out which macOS SDK will be used

xcrun -sdk macosx --show-sdk-version

Binary Size Minimization#

To produce a smaller binary use the CMake flags CMAKE_BUILD_TYPE=MinSizeRel and BUILD_SHARED_LIBS=ON.

The MLX CMake build has several additional options to make smaller binaries. For example, if you don’t need the CPU backend or support for safetensors and GGUF, you can do:

cmake .. \
  -DCMAKE_BUILD_TYPE=MinSizeRel \
  -DBUILD_SHARED_LIBS=ON \
  -DMLX_BUILD_CPU=OFF \
  -DMLX_BUILD_SAFETENSORS=OFF \
  -DMLX_BUILD_GGUF=OFF \
  -DMLX_METAL_JIT=ON

THE MLX_METAL_JIT flag minimizes the size of the MLX Metal library which contains pre-built GPU kernels. This substantially reduces the size of the Metal library by run-time compiling kernels the first time they are used in MLX on a given machine. Note run-time compilation incurs a cold-start cost which can be anwywhere from a few hundred millisecond to a few seconds depending on the application. Once a kernel is compiled, it will be cached by the system. The Metal kernel cache persists accross reboots.

Troubleshooting#

Metal not found#

You see the following error when you try to build:

error: unable to find utility "metal", not a developer tool or in PATH

To fix this, first make sure you have Xcode installed:

xcode-select --install

Then set the active developer directory:

sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer

x86 Shell#

If the output of uname -p is x86 then your shell is running as x86 via Rosetta instead of natively.

To fix this, find the application in Finder (/Applications for iTerm, /Applications/Utilities for Terminal), right-click, and click “Get Info”. Uncheck “Open using Rosetta”, close the “Get Info” window, and restart your terminal.

Verify the terminal is now running natively the following command:

$ uname -p
arm

Also check that cmake is using the correct architecture:

$ cmake --system-information | grep CMAKE_HOST_SYSTEM_PROCESSOR
CMAKE_HOST_SYSTEM_PROCESSOR "arm64"

If you see "x86_64", try re-installing cmake. If you see "arm64" but the build errors out with “Building for x86_64 on macOS is not supported.” wipe your build cache with rm -rf build/ and try again.