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.8

  • 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 git@github.com:ml-explore/mlx.git mlx && cd mlx

Install nanobind with:

pip install git+https://github.com/wjakob/nanobind.git@2f04eac452a6d9142dedb957701bdb20125561e4

Then simply build and install MLX using pip:

env CMAKE_BUILD_PARALLEL_LEVEL="" pip install .

For developing use an editable install:

env CMAKE_BUILD_PARALLEL_LEVEL="" pip install -e .

To make sure the install is working run the tests with:

pip install ".[testing]"
python -m unittest discover python/tests

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

pip install ".[dev]"
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 git@github.com: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_PYTHON_BINDINGS

OFF

MLX_METAL_DEBUG

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

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 ouptut 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 cahce with rm -rf build/ and try again.