[BUG] MLX library not found

[mdales]

Describe the bug Python package 0.26.5 fails to find libmlx on both macOS and Ubuntu latest

To Reproduce

Include code snippet

>>> import mlx.core as mx
Traceback (most recent call last):
  File "<python-input-0>", line 1, in <module>
    import mlx.core as mx
ImportError: dlopen(/Users/michael/Dev/yirgacheffe/venv2/lib/python3.13/site-packages/mlx/core.cpython-313-darwin.so, 0x0002): Library not loaded: @rpath/libmlx.dylib
  Referenced from: <4A900F73-B9D2-3E99-A6C1-329FD9D9503C> /Users/michael/Dev/yirgacheffe/venv2/lib/python3.13/site-packages/mlx/core.cpython-313-darwin.so
  Reason: tried: '/Users/michael/Dev/yirgacheffe/venv2/lib/python3.13/site-packages/mlx/lib/libmlx.dylib' (no such file), '/Users/distiller/project/build/temp.macosx-14.6-arm64-cpython-313/mlx.core/libmlx.dylib' (no such file), '/System/Volumes/Preboot/Cryptexes/OS/Users/distiller/project/build/temp.macosx-14.6-arm64-cpython-313/mlx.core/libmlx.dylib' (no such file), '/Users/michael/Dev/yirgacheffe/venv2/lib/python3.13/site-packages/mlx/lib/libmlx.dylib' (no such file), '/Users/distiller/project/build/temp.macosx-14.6-arm64-cpython-313/mlx.core/libmlx.dylib' (no such file), '/System/Volumes/Preboot/Cryptexes/OS/Users/distiller/project/build/temp.macosx-14.6-arm64-cpython-313/mlx.core/libmlx.dylib' (no such file), '/opt/homebrew/lib/libmlx.dylib' (no such file), '/System/Volumes/Preboot/Cryptexes/OS/opt/homebrew/lib/libmlx.dylib' (no such file), '/opt/homebrew/lib/libmlx.dylib' (no such file), '/System/Volumes/Preboot/Cryptexes/OS/opt/homebrew/lib/libmlx.dylib' (no such file)

Expected behavior Import should succeed. Works with 0.26.3.

Desktop (please complete the following information):

• OS Version: macOS 15.5, Ubuntu 24.04.2 LTS
• Version: 0.26.5 from pip

Additional context Ubuntu versions failure can be seen in this CI run:

https://github.com/quantifyearth/yirgacheffe/actions/runs/16439765910/job/46457636691

This project has used mlx successfully for the last few months, CI just failed for the first time today. I manually checked with 0.26.3 and that is okay.

[mdales]

Locally trying to repro, within the same Python virtual environment I can just downgrade MLX only to the previous release and things work, but then upgrading MLX only causes the failure.

[mdales]

I changed my CI job to use mlx[cpu] and that no longer has the issue. However, using just mlx on macOS I do still have the issue.

Successful run is here: https://github.com/quantifyearth/yirgacheffe/actions/runs/16440498217/job/46460010733

I guess on Linux this is considered a user error due to the API update?

[awni]

How did you install the macOS library? I just tried it via pip and it worked fine. Could you share the output of:

pip show mlx

And

pip show mlx-metal

[hansvdam]

I have the same issue. Downgraded to 26.3 and the problem disappeared:

% pip show mlx
WARNING: Ignoring invalid distribution ~enacity (/Users/hansvandam/Projects/PyCharm/openAIAssistant1/venv/lib/python3.12/site-packages)
Name: mlx
Version: 0.26.5
Summary: A framework for machine learning on Apple silicon.
Home-page: https://github.com/ml-explore/mlx
Author: MLX Contributors
Author-email: [email protected]
License: MIT
Location: /Users/hansvandam/Projects/PyCharm/openAIAssistant1/venv/lib/python3.12/site-packages
Requires: mlx-metal
Required-by: mlx-lm

[awni]

Can you do pip show mlx-metal as well?

[mdales]

From my failing setup:

$ pip show mlx-metal          
Name: mlx-metal
Version: 0.26.5
Summary: A framework for machine learning on Apple silicon.
Home-page: https://github.com/ml-explore/mlx
Author: MLX Contributors
Author-email: [email protected]
License: MIT
Location: /Users/michael/Dev/yirgacheffe/venv2/lib/python3.13/site-packages
Requires:
Required-by: mlx
$ pip show mlx                      
Name: mlx
Version: 0.26.5
Summary: A framework for machine learning on Apple silicon.
Home-page: https://github.com/ml-explore/mlx
Author: MLX Contributors
Author-email: [email protected]
License: MIT
Location: /Users/michael/Dev/yirgacheffe/venv2/lib/python3.13/site-packages
Requires: mlx-metal
Required-by:

The install would have been by hand for the virtual environment - so pip install mlx. Prior to this I had 0.22.x installed.

[mdales]

On a fresh virtual environment everything is working :/

$  python3 -m venv /tmp/venv      
 lattebit  ~  $  . /tmp/venv/bin/activate.fish            
(venv)  venv  lattebit  ~  $  pip install mlx                   
Collecting mlx
  Downloading mlx-0.26.5-cp39-cp39-macosx_15_0_arm64.whl (491 kB)
     |████████████████████████████████| 491 kB 4.3 MB/s
Collecting mlx-metal==0.26.5
  Downloading mlx_metal-0.26.5-py3-none-macosx_15_0_arm64.whl (32.9 MB)
     |████████████████████████████████| 32.9 MB 30.1 MB/s
Installing collected packages: mlx-metal, mlx
Successfully installed mlx-0.26.5 mlx-metal-0.26.5
WARNING: You are using pip version 21.2.4; however, version 25.1.1 is available.
You should consider upgrading via the '/private/tmp/venv/bin/python3 -m pip install --upgrade pip' command.
(venv)  venv  lattebit  ~  $  python3              
Python 3.9.6 (default, Apr 30 2025, 02:07:17)
[Clang 17.0.0 (clang-1700.0.13.5)] on darwin
Type "help", "copyright", "credits" or "license" for more information.
>>> import mlx.core as mx
>>>

I could just rebuild my other environment, but is there anything you'd like me to try first?

This is the contents of my current environment:

alabaster==1.0.0
astroid==3.3.8
babel==2.17.0
build==1.2.2.post1
certifi==2025.6.15
charset-normalizer==3.4.2
coverage==7.6.12
dill==0.3.9
docutils==0.21.2
filelock==3.18.0
fsspec==2025.5.1
GDAL==3.10.0
h3==4.1.2
id==1.5.0
idna==3.10
imageio==2.37.0
imagesize==1.4.1
iniconfig==2.0.0
isort==5.13.2
jaraco.classes==3.4.0
jaraco.context==6.0.1
jaraco.functools==4.1.0
Jinja2==3.1.6
keyring==25.6.0
lazy_loader==0.4
markdown-it-py==3.0.0
MarkupSafe==3.0.2
mccabe==0.7.0
mdurl==0.1.2
mlx==0.26.5
mlx-metal==0.26.5
more-itertools==10.7.0
mpmath==1.3.0
mypy==1.14.1
mypy-extensions==1.0.0
networkx==3.4.2
nh3==0.2.21
numpy==2.2.2
packaging==24.2
pillow==11.1.0
platformdirs==4.3.6
pluggy==1.5.0
Pygments==2.19.1
pylint==3.3.3
pyproject_hooks==1.2.0
pytest==8.3.4
pytest-cov==6.0.0
readme_renderer==44.0
requests==2.32.4
requests-toolbelt==1.0.0
rfc3986==2.0.0
rich==14.0.0
roman-numerals-py==3.1.0
scikit-image==0.25.0
scipy==1.15.1
setuptools==80.9.0
snowballstemmer==3.0.1
Sphinx==8.2.3
sphinxcontrib-applehelp==2.0.0
sphinxcontrib-devhelp==2.0.0
sphinxcontrib-htmlhelp==2.1.0
sphinxcontrib-jsmath==1.0.1
sphinxcontrib-qthelp==2.0.0
sphinxcontrib-serializinghtml==2.0.0
sympy==1.14.0
tifffile==2025.1.10
tomlkit==0.13.2
torch==2.7.1
twine==6.1.0
typing_extensions==4.12.2
urllib3==2.4.0

[awni]

Thanks. Could you also list these two directories:

/Users/michael/Dev/yirgacheffe/venv2/lib/python3.13/site-packages/mlx

/Users/michael/Dev/yirgacheffe/venv2/lib/python3.13/site-packages/mlx/lib

[mdales]

$  ls -la /Users/michael/Dev/yirgacheffe/venv2/lib/python3.13/site-packages/mlx
total 2664
-rw-r--r--@   1 michael  staff      578 22 Jul 10:21 __main__.py
drwxr-xr-x@   8 michael  staff      256 22 Jul 10:21 __pycache__/
-rw-r--r--@   1 michael  staff      303 22 Jul 10:21 _os_warning.py
-rw-r--r--@   1 michael  staff      321 22 Jul 10:21 _reprlib_fix.py
drwxr-xr-x@  15 michael  staff      480 22 Jul 10:21 ./
drwxr-xr-x@ 155 michael  staff     4960 22 Jul 10:21 ../
-rwxr-xr-x@   1 michael  staff  1300728 22 Jul 10:21 core.cpython-313-darwin.so*
-rw-r--r--@   1 michael  staff    25668 22 Jul 10:21 distributed_run.py
-rw-r--r--@   1 michael  staff     3294 22 Jul 10:21 extension.py
drwxr-xr-x@   3 michael  staff       96 22 Jul 10:21 include/
drwxr-xr-x@   8 michael  staff      256 22 Jul 10:21 nn/
drwxr-xr-x@   6 michael  staff      192 22 Jul 10:21 optimizers/
-rw-r--r--@   1 michael  staff        1 22 Jul 10:21 py.typed
drwxr-xr-x@   3 michael  staff       96 22 Jan 11:46 share/
-rw-r--r--@   1 michael  staff     9972 22 Jul 10:21 utils.py
(venvhb)  venvhb  lattebit  yirgacheffe  mwd-docs  $  ls -la /Users/michael/Dev/yirgacheffe/venv2/lib/python3.13/site-packages/mlx/lib
ls: /Users/michael/Dev/yirgacheffe/venv2/lib/python3.13/site-packages/mlx/lib: No such file or directory

[mdales]

I thought maybe it's because I'm using homebrew python for my project as I need newer than Python 3.9, but it also works on a clean virtual environment using Python3 from homebrew.

[awni]

Strange it didn’t include the library in the old one.. I don’t know why that is. I’ll double check that it is in the wheel and get back to you

[awni]

Ok I think I understand the issue. We changed the way MLX packaging works in 0.26.5. It now installs the MLX binary via mlx-metal. What's happening is if you pip install -U mlx it installs the library (via mlx-metal) to the MLX site packages directory. It then uninstalls the old mlx which attempts to wipes the old library but inadvertently wipes the new one. It then installs the new mlx

This is only an issue when upgrading to 0.26.5 or later from a version lower than 0.26.5. When upgrading 0.26.5 onward it shouldn't be an issue.

For now a simple fix workaround is to do this in two steps:

pip uninstall mlx mlx-metal
pip install mlx==0.26.5 

[junpeiz]

I also hit this issue. Thanks for providing the solution!

Only uninstalling mlx doesn't work for me, but I confirmed that uninstalling both mlx and mlx-metal, and then install mlx works for me.

pip uninstall mlx mlx-metal
pip install mlx==0.26.5

[awni]

Right if you already installed mlx==0.26.5 you'd have to uninstall both mlx and mlx-metal. If you haven't yet installed it then uninstall mlx before installing the new version.

[mdales]

Just to confirm I uninstalled mlx-core and mlx from the impacted virtual env and reinstalled them and it now works fine. Thanks for your help @awni

[hermeschen1116]

Hi, I also faced this problem with Python 3.12.11 recently on macOS 26, and I've already reinstalled them several times. The only solution for me is to install mlx using brew then everything works. Is there other solution for this?

Here are the packages I installed.

󰄛 ❯ uv pip list | rg -i mlx
mlx                            0.27.1
mlx-lm                         0.26.2
mlx-metal                      0.27.1
mlx-vlm                        0.3.2

[awni]

Could you share the error message you are getting? It looks like mlx is installed correctly for you or am I missing something?

[hermeschen1116]

Could you share the error message you are getting? It looks like mlx is installed correctly for you or am I missing something?

Traceback (most recent call last):
  File "/Users/hermeschen/Repo/work/taiwan-license-plate-recognition/packages/model-utils/src/scripts/recognition/eval.py", line 11, in <module>
    from mlx_vlm.generate import generate
  File "/Users/hermeschen/Repo/work/taiwan-license-plate-recognition/.venv/lib/python3.12/site-packages/mlx_vlm/__init__.py", line 3, in <module>
    from .convert import convert
  File "/Users/hermeschen/Repo/work/taiwan-license-plate-recognition/.venv/lib/python3.12/site-packages/mlx_vlm/convert.py", line 7, in <module>
    import mlx.core as mx
ImportError: dlopen(/Users/hermeschen/Repo/work/taiwan-license-plate-recognition/.venv/lib/python3.12/site-packages/mlx/core.cpython-312-darwin.so, 0x0002): Library not loaded: @rpath/libmlx.dylib
  Referenced from: <8B6A45F7-00BF-3CEA-9AFF-CD76D4BC76F0> /Users/hermeschen/.cache/uv/archive-v0/ty8nQNp4RJWPxIVg62e6-/mlx/core.cpython-312-darwin.so
  Reason: tried: '/Users/hermeschen/.cache/uv/archive-v0/ty8nQNp4RJWPxIVg62e6-/mlx/lib/libmlx.dylib' (no such file), '/Users/distiller/project/build/temp.macosx-14.0-arm64-cpython-312/mlx.core/libmlx.dylib' (no such file), '/System/Volumes/Preboot/Cryptexes/OS/Users/distiller/project/build/temp.macosx-14.0-arm64-cpython-312/mlx.core/libmlx.dylib' (no such file), '/Users/hermeschen/.cache/uv/archive-v0/ty8nQNp4RJWPxIVg62e6-/mlx/lib/libmlx.dylib' (no such file), '/Users/distiller/project/build/temp.macosx-14.0-arm64-cpython-312/mlx.core/libmlx.dylib' (no such file), '/System/Volumes/Preboot/Cryptexes/OS/Users/distiller/project/build/temp.macosx-14.0-arm64-cpython-312/mlx.core/libmlx.dylib' (no such file), '/opt/homebrew/lib/libmlx.dylib' (no such file), '/System/Volumes/Preboot/Cryptexes/OS/opt/homebrew/lib/libmlx.dylib' (no such file), '/opt/homebrew/lib/libmlx.dylib' (no such file), '/System/Volumes/Preboot/Cryptexes/OS/opt/homebrew/lib/libmlx.dylib' (no such file)

I think it's the same problem? And it neither works in 3.13

[awni]

Please try the following two commands in succession:

pip uninstall mlx mlx-metal
pip install mlx==0.27.1

[hermeschen1116]

I still got the same error message.

[awni]

Maybe try installing with a fresh conda environment?

[hermeschen1116]

But I use uv to manage my project. And I do uv sync --reinstall each time before I run my script. It works before, I don't know if it's because of the newer version of mlx.

[awni]

Ok in that case, could you share the sequence of commands you ran and we can see if we can reproduce the installation issue on our end?

[hermeschen1116]

I just do uv sync -U --refresh --reinstall --compile-bytecode and uv run to execute my python script (using mlx_vlm to do some OCR). And I'm using macOS 26 beta 4 on M2 Air 15'.

[Crear12]

Right if you already installed mlx==0.26.5 you'd have to uninstall both mlx and mlx-metal. If you haven't yet installed it then uninstall mlx before installing the new version.

I think this can be pinned as the solution. Just fixed my Anaconda environments by uninstalling both mlx and mlx-metal: pip uninstall mlx mlx-metal and then pip install mlx.

[hermeschen1116]

Please try the following two commands in succession:

pip uninstall mlx mlx-metal
pip install mlx==0.27.1

The problem is solved when I downgrade to mlx 0.26.3 and in this version mlx does not require mlx-metal. Maybe the problem is related to it?

󰄛 ❯ uv pip list | rg -i mlx
mlx                            0.26.3
mlx-lm                         0.26.2
mlx-vlm                        0.3.2

[Crear12]

Please try the following two commands in succession:

pip uninstall mlx mlx-metal
pip install mlx==0.27.1

The problem is solved when I downgrade to mlx 0.26.3 and in this version mlx does not require mlx-metal. Maybe the problem is related to it?

󰄛 ❯ uv pip list | rg -i mlx mlx 0.26.3 mlx-lm 0.26.2 mlx-vlm 0.3.2

I think it's caused by Apple's latest decision to provide CUDA compatibility...There's a change of how MLX is managed and used.

[hermeschen1116]

Please try the following two commands in succession:

pip uninstall mlx mlx-metal
pip install mlx==0.27.1

The problem is solved when I downgrade to mlx 0.26.3 and in this version mlx does not require mlx-metal. Maybe the problem is related to it? 󰄛 ❯ uv pip list | rg -i mlx mlx 0.26.3 mlx-lm 0.26.2 mlx-vlm 0.3.2

I think it's caused by Apple's latest decision to provide CUDA compatibility...There's a change of how MLX is managed and used.

But I think we should get the Apple Silicon specified package if installing it on Mac as they said in doc?

[awni]

I just do uv sync -U --refresh --reinstall --compile-bytecode and uv run

@hermeschen1116 what are the full steps you took. That's not quite enough information to repro what you are doing. Where are you running that command? In a clone of mlx-vlm?

[hermeschen1116]

Sorry but I don't really understand what you mean the full steps. I did what I mentioned before in my project and the uv sync command will automatically create the virtual environment and install all the packages specified in pyproject.toml for me. Then I just run any scripts in my project using uv run.