Skip to content
Lantern

Install

  • For the prebuilt app (Lantern.dmg): a Mac with Apple Silicon (M1 or newer) and macOS 26.2 (Tahoe) or newer: the app is made for Liquid Glass, and MLX’s libraries need macOS 26.2. Python 3.12, all packages and the AVFoundation media helper are inside Lantern.app; no Xcode, Homebrew, uv or ffmpeg is needed (brew install ffmpeg is optional if you index .mkv or .webm videos).
  • For building from source (./install.sh) and the lantern CLI:
What Why Install
Mac with Apple Silicon (tested: M4, 16 GB) MLX runs on Apple Silicon only –
Xcode Command Line Tools compiler, git xcode-select --install
Xcode 26 builds the menu bar app (macOS 26 SDK) App Store
Homebrew package manager https://brew.sh
uv Python environment and dependencies brew install uv
Python 3.12 the daemon; installed by uv, not the system Python automatic with uv sync
ffmpeg (optional) MKV and WebM recordings only; everything else is decoded by macOS itself (AVFoundation) brew install ffmpeg

uv sync installs everything else into the project’s .venv (nothing global, no PyTorch): MLX and a pinned mlx-vlm commit (EmbeddingGemma 2 support), transformers, tokenizers, sqlite-vec, tree-sitter-language-pack, pathspec, charset-normalizer, mlx-whisper, pillow, soundfile, watchdog, and pyobjc-framework-Vision / pyobjc-framework-Quartz (Python bindings for macOS’s text recognition and PDFKit; no models to download).

The python.org Python (e.g. 3.13) does not work: it cannot load SQLite extensions, which sqlite-vec needs. The Python that uv installs can.

Installation

Section titled “Installation”
Section titled “Via Homebrew (Recommended)”
Terminal window
brew install --cask misterekkk/tap/lantern

Download the app (Lantern.dmg)

Section titled “Download the app (Lantern.dmg)”
  1. Download Lantern.dmg from Releases (or the latest artifact of the Build Lantern.dmg workflow in Actions), open it and drag Lantern to Applications.
  2. Because the build is signed ad-hoc (without a paid Apple Developer ID), macOS Gatekeeper blocks the first launch of a downloaded copy. Allow it once:
    • either try to open Lantern in /Applications, then go to System Settings → Privacy & Security and click Open Anyway at the bottom (or right-click Lantern.app in Finder → Open),
    • or remove the quarantine attribute in Terminal:
      Terminal window
      xattr -cr /Applications/Lantern.app
  3. Click the Lantern icon in the menu bar and click Download to fetch the search model (~1.2 GB; optional checkboxes add Whisper for recordings and SigLIP 2 for photos). Models can also be downloaded later in Settings → Performance. Quick search (apps, System Settings, calculator, dictionary) works immediately while the model downloads.

From source (./install.sh)

Section titled “From source (./install.sh)”

For the lantern command-line tool, manual page, and building from a checkout:

Terminal window
git clone https://github.com/misterekkk/lantern.git && cd lantern
./install.sh

The script checks the Mac (Apple Silicon, macOS 26.2+, Command Line Tools), installs uv and ffmpeg (for MKV/WebM) with Homebrew (with Homebrew analytics off for its own calls; if Homebrew is missing it asks before running the official installer), runs uv sync, downloads the required model and asks about the optional ones, checks that search works offline, and builds the app into /Applications when Xcode 26 is present. It can be run again at any time: finished steps are skipped. ./install.sh --all installs everything without questions, ./install.sh --minimal only the command line and the required model; --no-app, --test (also run the tests). It never installs the LaunchAgent.

It also makes lantern and man lantern work in every terminal without sudo: two symlinks into this folder (~/.local/bin/lantern, ~/.local/share/man/man1/lantern.1, so git pull updates both), and, if you agree, one PATH line in ~/.zprofile between # >>> lantern >>> markers. ./install.sh --uninstall removes the links, that line and (if you say so) the app; your index and the models stay until you delete them (it prints how).

Step by step

Section titled “Step by step”

The same steps by hand:

Terminal window
# 1. System tools
xcode-select --install
# Homebrew: https://brew.sh. If `brew` is not on your PATH (Apple Silicon):
echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile
eval "$(/opt/homebrew/bin/brew shellenv)"
brew install uv ffmpeg


# 2. Project and dependencies (uv downloads Python 3.12 into ~/.local/share/uv)
cd lantern
uv sync


# 3. One-time model download (needs internet; models go to ~/.cache/huggingface/hub/)
#    a) EmbeddingGemma 2, MLX 8-bit (~1.2 GB) — required
uv run hf download mlx-community/embeddinggemma-2-8bit --revision 7505ef2f8ddef45efef6d060865f27989b3c9cec
#    b) Whisper for transcripts (~1.6 GB) — skip if you do not index recordings or use --no-transcribe
uv run hf download mlx-community/whisper-large-v3-turbo --revision a4aaeec0636e6fef84abdcbe3544cb2bf7e9f6fb
#    c) SigLIP 2 for photo search (~0.8 GB + ~0.2 GB) — optional; without it EmbeddingGemma 2 ranks photos alone
uv run hf download google/siglip2-base-patch16-224 --revision 75de2d55ec2d0b4efc50b3e9ad70dba96a7b2fa2
uv run hf download mlx-community/siglip2-base-patch16-224-8bit --revision 5249fc157310584fe99dae6964707278eb6df50f


# 4. Check
uv run lantern --help
uv run pytest


# 5. Menu bar app
app/build.sh --install        # dev bundle (.venv), or app/build.sh --dmg for a self-contained Lantern.dmg
open /Applications/Lantern.app

Lantern always loads models with HF_HUB_OFFLINE=1 TRANSFORMERS_OFFLINE=1 HF_HUB_DISABLE_TELEMETRY=1 DO_NOT_TRACK=1; an automated test checks that loading and embedding open no network connection.

Building the app needs Xcode 26 (the script selects it with DEVELOPER_DIR, without changing xcode-select). It signs with your “Apple Development” certificate if you have one (Xcode → Settings → Accounts → Manage Certificates); otherwise it signs ad hoc and macOS may ask for folder permissions again after every rebuild. app/build.sh --dmg bundles Python 3.12 and the daemon inside Lantern.app and creates app/build/Lantern.dmg.