manicule-mlx
The Metal-native embedding backend for manicule, on Apple Silicon.
uv pip install manicule manicule-mlx
Then select it:
[embedding]
provider = "mlx"
License — read this first
This package is GPL-3.0-or-later. manicule itself is MIT. They live in one repository and they are not under one license.
| License | |
|---|---|
manicule — everything under src/manicule/ |
MIT |
manicule-plugin-example, manicule-plugin-hostile |
MIT |
manicule-mlx — everything under this directory |
GPL-3.0-or-later |
The reason is one dependency. mlx-embeddings is GPL-3.0, and a backend that links it is very
likely a derivative work. Rather than make the whole project copyleft to obtain one accelerated
backend — which is what manicule did until this split — the backend that carries the obligation
is packaged on its own. MIT code may be incorporated into a GPL work freely; the reverse is not
true, which is why the boundary falls exactly here.
What that means in practice:
- Installing manicule alone gets you an MIT program with no GPL anywhere in its dependency
closure. The
onnxbackend is the default and runs everywhere. - Installing both produces a combined work on your machine that is GPL-3.0. Running it imposes nothing on you — the GPL's obligations attach to distribution. If you redistribute the combination, they attach to you.
- Writing a plugin for manicule does not make it GPL. Writing one that imports
manicule_mlxvery likely does.
Nothing here decides it for you. Take advice if you intend to distribute either manicule or a plugin under other terms.
Why it exists
On Apple Silicon this backend is roughly 4–5× faster than onnxruntime on the indexing path.
Measured on an M4 Max, BAAI/bge-m3, 512-token chunks, batch 32, five interleaved repetitions:
| Chunk length | MLX | onnxruntime | Ratio |
|---|---|---|---|
| 128 tokens | 136.7 chunks/s | 24.5 chunks/s | 5.58× |
| 256 tokens | 64.1 chunks/s | 12.3 chunks/s | 5.23× |
| 512 tokens | 25.6 chunks/s | 6.0 chunks/s | 4.28× |
| ~24 tokens (a query) | 98.7 chunks/s | 80.0 chunks/s | 1.23× |
The gap is on indexing, not on queries. A corpus of 270 000 chunks is about 3 hours here and about 12 on onnxruntime; a single query differs by roughly two milliseconds, which vanishes under the generation call that follows it.
The vectors are the same either way. Cosine agreement between the two backends is
0.99999998 with a largest component difference of 2.1 × 10⁻⁵, retrieval ranking is identical,
and the two write byte-identical canonical fingerprints. backend is excluded from
EmbedFingerprint identity precisely so that installing or removing this package is never a
re-embed. tests/test_parity.py in this package is what licenses that claim, and it is the
reason the test lives here rather than in manicule: the plugin asserts parity against the
reference, in the same CI run.
Requirements
Apple Silicon. mlx-embeddings is marked sys_platform == 'darwin' and platform_machine == 'arm64', so on any other platform this distribution installs and the backend refuses at setup
with a message naming onnx — rather than failing to install and taking the rest of an
environment with it.
1 maintainer
Release files for manicule-mlx 0.2.7
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| manicule_mlx-0.2.7.tar.gz | 38.5 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| manicule_mlx-0.2.7-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 62.8 kB
Release files / manicule_mlx-0.2.7.tar.gz
| Download URL | manicule_mlx-0.2.7.tar.gz |
|---|---|
| Size | 38.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
87c4ae1f188cb877587a5f9fe193e0929386cc531128f708f8acd82d9b3d4138
|
|
BLAKE2b-256 checksum How to use checksums |
7e872d395c38cc4a2844d333ca652b2c35dac2b6940777f8dcdb503063760127
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 16, 2026.
Transparency logRelease files / manicule_mlx-0.2.7-py3-none-any.whl
| Download URL | manicule_mlx-0.2.7-py3-none-any.whl |
|---|---|
| Size | 24.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
71dab265670f68f629275eaaaf75caac25b2adba79980e56b1dec5a834498bee
|
|
BLAKE2b-256 checksum How to use checksums |
86b15ebff3f92f6baeae5801682222c590c968244015ba1df4a2461b7705ece2
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 16, 2026.
Transparency log
