Install and requirements

Hardware

Apple Silicon only. MLX is Apple-only by design.

Working-memory footprint is non-negotiable: standard 1280×704 generation peaks at roughly 22 GiB resident, and HQ with the Q8 dev transformer at roughly 38 GiB. Tier is detected once at boot from RAM and exposed to the UI via body[data-cap-tier="q4|q8"]. Set LTX_FORCE_CAP_TIER=q4 to preview the Compact surface from a higher-tier machine.

RAM is not the only gate, and on LTX-2.5 it is not the interesting one. The table above answers “what can this Mac’s memory serve”. Whether trained characters render faithfully, and whether the High tier exists at all, are questions about which weight packs are on disk — a 64 GB Mac holding only the base pack is Comfortable-tier and still cannot do either. The panel tracks that separately (body[data-q8-pack]), and every surface that offers a download says which pack and how big.

Install

Via Pinokio (recommended)

1. Install Pinokio.
2. In Pinokio: Discover -> Download from URL -> paste https://github.com/mrbizarro/phosphene.
3. Click Install.
4. Click Start -> Open Panel -> http://127.0.0.1:8198.

Pinokio handles the hardware gate, the vendored ltx-2-mlx clone at its pinned tag, the uv-managed Python 3.11 venv, the runtime patches, and the model download.

What a fresh install fetches (~37 GB): LTX-2.5’s engine (20.74 GB) and its Gemma 4 text encoder (6.73 GB) — the generation the panel renders with — plus the 22 MB live-preview decoder; Gemma 3 (~6 GB), which is what Enhance and the Storyboard planner run on; and three control LoRAs (~4 GB) for the Colorize, Ingredients and Motion Control modes — all three public and un-gated, no token needed. Every step is resumable. (HDR uses a fourth, gated LoRA — that one needs a Hugging Face token in Settings, and the panel fetches it on first use.)

LTX-2.3 is not downloaded. It is needed only to train a character — the trainer runs against 2.3, not 2.5 — so the panel offers it (~20 GB, plus the ~21 GB full-precision dev transformer) the moment you open the Train Character tab, and in Settings → Models any time. The three control LoRAs are 2.3-trained, and Lightricks has published exactly one LTX-2.5 IC-LoRA to date (a pixel spatial upscaler): Ingredients is therefore refused on 2.5 with the reason, and Motion Control still transfers the motion but loses most of the prompt’s grip on the new subject — see docs/MOTION_CONTROL.md. Everything else renders on LTX-2.5.

For trained characters and voices, install the LTX-2.5 Q8 weights (30.02 GB) from Settings → Models. The High tier additionally needs the High add-on (29.50 GB), which installs into the same folder.

If you have a Hugging Face token, paste it under Settings in the panel. Downloads run roughly 10x faster, and the same token unlocks the one gated LoRA (HDR). Motion Control does not need it — the Union Control weight is public.

Linux on Apple Silicon - community-maintained, best effort

Phosphene can run on Linux on M1/M2 Macs (Omarchy, MLX through the third-party omarchy-mlx Vulkan build), contributed and maintained by @joshuaswarren. It is not tested by the release gates and Pinokio does not install it: run bash scripts/linux/install.sh, then ./run_panel.sh. Details, the H3 engine and measured runs: docs/LINUX.md.

Manual install

# 1. Clone Phosphene + the MLX port (pinned to our LTX-2.5 fork build).
git clone https://github.com/mrbizarro/phosphene.git
cd phosphene
git clone https://github.com/dgrauet/ltx-2-mlx.git ltx-2-mlx
cd ltx-2-mlx
git remote add fork https://github.com/mrbizarro/ltx-2-mlx.git
git fetch fork +refs/tags/v0.14.19+ltx25.7:refs/tags/v0.14.19+ltx25.7
git checkout v0.14.19+ltx25.7
cd ..

# 2. Create the Python 3.11 venv inside ltx-2-mlx (uv-managed).
#    Every install below uses the `uv` on your PATH — `--seed` puts pip,
#    setuptools and wheel into the venv, not uv, so there is no env/bin/uv.
cd ltx-2-mlx
uv venv --python 3.11 --seed env

# 3. Install the MLX pipeline + trainer packages. Pin mlx to 0.31.1 —
#    0.31.2 attenuates the LTX vocoder by 22 dB — and cap transformers below
#    5.13.0, which breaks every generation. Both on the same resolve.
uv pip install --python env/bin/python \
  'mlx==0.31.1' 'mlx-lm==0.31.1' 'mlx-metal==0.31.1' 'transformers>=5.0.0,<5.13.0'
# --build-constraints pins hatchling below 1.32, which rejects upstream's
# `readme = "../../README.md"` and fails metadata generation. See
# pip-build-constraints.txt. The first pass resolves the packages'
# dependencies (mlx-arsenal among them); the second replaces the editable
# workspace links it leaves with real copies, which the codec patch needs.
uv pip install --python env/bin/python \
  --build-constraints ../pip-build-constraints.txt \
  ./packages/ltx-core-mlx ./packages/ltx-pipelines-mlx ./packages/ltx-trainer
uv pip install --python env/bin/python --reinstall --no-deps \
  --build-constraints ../pip-build-constraints.txt \
  ./packages/ltx-core-mlx ./packages/ltx-pipelines-mlx ./packages/ltx-trainer
uv pip install --python env/bin/python \
  pyyaml pydantic tqdm rich
# mlx-vlm powers Gemma 3 auto-caption. --no-deps so it doesn't drag mlx-lm past 0.31.1.
uv pip install --python env/bin/python --no-deps 'mlx-vlm==0.4.4'
# Agent + downloader + hub pin range.
uv pip install --python env/bin/python pillow numpy 'huggingface-hub>=1.5.0,<2.0' \
  'hf_transfer>=0.1.6' 'litellm>=1.83.14' 'smolagents>=1.24.0'
cd ..

# 4. Apply the runtime patches (idempotent, fail loud on upstream drift).
./ltx-2-mlx/env/bin/python3.11 patch_ltx_codec.py

# 5. Download LTX-2.5 — the base install: the engine (20.74 GB), its Gemma 4
#    text encoder (6.73 GB) and the 22 MB live-preview decoder. 27.5 GB total,
#    resumable and sha256-verified. NOT `hf download`: these are our own
#    quantisation of a gated upstream, mirrored as GitHub release assets.
./ltx-2-mlx/env/bin/python3.11 scripts/fetch_pack_release.py \
  --repo-key q4_25 --repo-key gemma4_25 --repo-key tae

# 5b. (Optional) The Q8 weights (30.02 GB) — what trained characters and
#     voices need. The High tier additionally needs the High add-on (29.50 GB).
./ltx-2-mlx/env/bin/python3.11 scripts/fetch_pack_release.py --repo-key q8_25

# 6. (Optional) Image tab — install mflux + apply the FBCache patch.
uv pip install --python ltx-2-mlx/env/bin/python 'mflux==0.18.0'
uv pip install --python ltx-2-mlx/env/bin/python --reinstall --no-deps 'mflux==0.18.0'
uv pip install --python ltx-2-mlx/env/bin/python 'mlx-teacache==0.4.1'
./ltx-2-mlx/env/bin/python3.11 patch_mflux_fbcache.py

# 7. (Optional) HiDream — separate one-time clone for the photoreal engine.
#    Clone HIDREAM-O1-MLX-LAB-active into your home directory, or set
#    HIDREAM_LAB_DIR to point at it.
#    git clone <hidream-lab-repo> ~/HIDREAM-O1-MLX-LAB-active

# 8. Launch the panel.
./ltx-2-mlx/env/bin/python3.11 mlx_ltx_panel.py

About the version pins: mlx 0.31.2 attenuates the LTX vocoder by 22 dB. Stay on 0.31.1. ltx-2-mlx is pinned to the fork tag v0.14.19+ltx25.7 (mrbizarro/ltx-2-mlx, commit bf419b6) — v0.14.19 plus the LTX-2.5 port, because upstream has no 2.5 branch. A tag, not a bare SHA: a force-push upstream would strand every install with an un-fetchable pin and a dead Update button. The installed packages report 0.14.19+ltx25.7 and _LTX_EXPECTED_VERSION must match that string exactly, or every render logs a VERSION SKEW warning. scripts/pinokio/ltx_checkout.sh holds the pin and node scripts/check_ltx_pin.js enforces the agreement. mflux 0.18.0 is the version patch_mflux_fbcache.py is line-targeted against, and it is pinned TOGETHER with mlx — mflux declares its own mlx range, so installing it with deps after pinning mlx can silently move mlx (node scripts/check_post_update.js fails if either moves alone). hatchling<1.32 (in pip-build-constraints.txt) is a build-time pin: 1.32 rejects the readme = "../../README.md" that all three upstream packages declare, which fails the wheel build on every tag.