Installation
Get Lucid installed on your Apple Silicon Mac.
Apple Silicon only
Lucid targets macOS on M1–M4 chips exclusively. Linux, Windows, and x86 are not supported.
Requirements
| Requirement | Version |
|---|---|
| macOS | 15 Sequoia or later |
| Apple chip | M1 / M2 / M3 / M4 |
| Python | 3.14 |
| Xcode Command Line Tools | latest |
One wheel covers macOS 15 and every later release. Python 3.14 is required: Lucid's type annotations rely on its lazy evaluation (PEP 649).
MLX 0.32's macOS 26 build is compiled for macOS 26.2. On an M5-class Mac still running 26.0 or 26.1 it can pick GPU kernels that release predates and fail at runtime; update macOS, or install the previous MLX with pip install "mlx<0.32". M1–M4 Macs are not affected.
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
# 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/ChanLumerico/lucid.git
cd lucid
python3.14 -m venv .venv && source .venv/bin/activate
pip install setuptools wheel cmake ninja "pybind11>=3.0,<3.1" mlx
pip install --no-build-isolation -e ".[dev]"Building from source requires CMake ≥ 3.24, Ninja ≥ 1.11, and the Xcode Command Line Tools. --no-build-isolation matters: the engine links against the libmlx.dylib of the MLX installed in your environment.