Installation
Get Lucid installed on your Apple Silicon Mac.
Apple Silicon only
Lucid targets macOS on Apple Silicon (M1 or later) exclusively. Linux, Windows, and x86-64 are not supported.
Requirements
| Requirement | Version |
|---|---|
| macOS | 26.2 Tahoe or later |
| Apple chip | Apple Silicon (M1 or later) |
| Python | 3.14 |
| MLX | Bundled (liblucid_mlx, MLX 0.32.3) |
| Xcode Command Line Tools | latest |
3.15.1 was the last release for macOS 15. Python 3.14 is required: Lucid's type annotations rely on its lazy evaluation (PEP 649).
The engine ships its own pinned MLX build (liblucid_mlx, MLX 0.32.3), compiled for macOS 26.2 and renamed so it loads alongside any mlx version you install (or none). Because pip has no platform tag for a macOS minor release, the wheel is tagged macosx_26_0, and import lucid enforces the macOS 26.2 floor at import time (refusing 26.0 and 26.1 with a clear message).
Install
pip install lucid-dlIf you manage multiple Python versions with pyenv or Conda, make sure you're on 3.14:
python --version # Python 3.14.x
pip install lucid-dlVerify
import lucid
print(lucid.__version__)
t = lucid.ones(3, 3, device="metal")
print(t.device) # metalAll good
If both lines print without error, Lucid is installed correctly and the MLX GPU backend is active.
Optional extras
# Pretrained weights / safetensors checkpoints
pip install "lucid-dl[models]"
# Zero-copy DLPack interop with the Python mlx package (mlx >= 0.32)
pip install "lucid-dl[mlx]"
# Development tools (ruff, mypy, pytest)
pip install "lucid-dl[dev]"
# Parity test suite against reference framework
pip install "lucid-dl[test]"Upgrading
pip install --upgrade lucid-dlBuilding from source
git clone https://github.com/lucid-official/lucid.git
cd lucid
python3.14 -m venv .venv && source .venv/bin/activate
pip install setuptools wheel cmake ninja "pybind11>=3.0,<3.1"
pip install --no-build-isolation -e ".[dev]"Building from source requires CMake ≥ 3.24, Ninja ≥ 1.11, and the Xcode Command Line Tools. During the build, python3 tools/fetch_mlx.py downloads, verifies (sha256), and stages the pinned mlx-metal wheel into ~/Library/Caches/lucid/mlx-metal as liblucid_mlx.dylib. For offline builds, pre-stage the cache with python3 tools/fetch_mlx.py or point LUCID_MLX_DIST_DIR at an already-unpacked mlx-metal wheel directory.