Skip to content

install.md

Latest commit

 

History

History
137 lines (90 loc) · 5.61 KB

install.md

File metadata and controls

137 lines (90 loc) · 5.61 KB
Raw

Install - Detailed Guide

Requirements

Requirement Details
Mac Apple Silicon
macOS macOS 26 (Tahoe) or later
Apple Intelligence Must be enabled in System Settings

Option 1: Homebrew (recommended)

brew install apfel

The tap publishes same-day releases (homebrew-core autobump can lag up to ~24h) and bundles the demo scripts as apfel-<name> commands:

brew install Arthur-Ficial/tap/apfel

The tap installs eight companion commands alongside apfel: apfel-cmd, apfel-explain, apfel-gitsum, apfel-mac-narrator, apfel-naming, apfel-oneliner, apfel-port, apfel-wtd. Source in demo/. The apfel- prefix avoids global PATH collisions (port would shadow MacPorts).

No build tools needed. See brew-install.md for troubleshooting.

Option 2: Nix (nixpkgs)

nix profile install nixpkgs#apfel-llm

Attribute name is apfel-llm because nixpkgs already has an unrelated apfel package (a particle-physics PDF library); the binary on $PATH is still apfel. The package landed via NixOS/nixpkgs#508084. See docs/nixpkgs.md for automation details.

Option 3: Build from source

Requires Swift 6.3+ with developer tools that include the macOS 27 SDK (Command Line Tools 27 or Xcode 27; since apfel 1.15.0 the sources use macOS 27 FoundationModels API behind runtime availability checks, so a 26.x SDK no longer compiles them - the binary still runs on macOS 26). Command Line Tools are enough - make install handles the SwiftPM 6.4 build-system workaround automatically. If you run swift build directly (outside the Makefile), add --build-system native - see the troubleshooting section below.

git clone https://github.com/Arthur-Ficial/apfel.git
cd apfel
make install

make install builds a release binary and installs to /usr/local/bin/apfel.

Verify your toolchain

# Check macOS version (needs 26+)
sw_vers

# Check Swift is installed
swift --version

# Check the active Apple SDK version (must be 27+)
xcrun --show-sdk-version

# If Swift is missing, install Command Line Tools:
xcode-select --install

Troubleshooting build errors

If make install fails with errors about missing FoundationModels types (e.g. LanguageModelSession.Usage, LanguageModelSession.Response, LanguageModelCapabilities) or the older tokenCount/contextSize errors, your SDK is too old. Since apfel 1.15.0, building from source requires the macOS 27 SDK. Fix:

# install Command Line Tools for macOS 27 (or Xcode 27)
xcode-select --install

# ensure the CLT developer dir is selected
sudo xcode-select -s /Library/Developer/CommandLineTools

# confirm the active SDK is 27+
xcrun --show-sdk-version

# retry
make install

xcrun --show-sdk-version must print 27.0 or newer.

Troubleshooting: "Unknown error parsing property list" (SwiftPM 6.4+)

If swift build fails with:

Unknown error parsing property list

SwiftPM 6.4 changed its default build system from native to swiftbuild, which does not work under Command Line Tools alone (swiftlang/swift-package-manager#10561). make install already handles this. If you run swift build directly, pass the flag yourself:

swift build -c release --build-system native

This workaround is temporary - the upstream fix is tracked at swiftlang/swift-package-manager#10561.

Alternative install methods

Mint

mint install Arthur-Ficial/apfel

mise

mise use -g github:Arthur-Ficial/apfel

Supports project-scoped installs (mise use github:Arthur-Ficial/apfel without -g). Installs directly from GitHub releases.

Verify

apfel 'Hello, world!'
apfel --version
apfel --release       # full build info

Troubleshooting: "Model unavailable"

If apfel --model-info shows available: no, the specific reason is printed alongside it. There are three possible causes, all from Apple's FoundationModels framework:

Reason What it means Fix
Apple Intelligence not enabled The toggle is off, or your device language and Siri language do not match, or Siri is set to an unsupported language System Settings > Apple Intelligence & Siri → turn on. Ensure Device Language and Siri Language are set to the SAME supported language (English, Danish, Dutch, French, German, Italian, Norwegian, Portuguese, Spanish, Swedish, Turkish, Chinese Simplified/Traditional, Japanese, Korean, Vietnamese).
Device not eligible Intel Mac, or Mac older than M1 Apple Silicon (M1 or later) is required. This is a hard Apple requirement - there is no workaround.
Model not ready On-device model is still downloading (~3-4 GB on first enable) Keep your Mac on Wi-Fi and power. Check download progress in System Settings > Apple Intelligence & Siri. Try again in a few minutes.

apfel is a thin wrapper around Apple's on-device model - it cannot turn on Apple Intelligence for you. Once the underlying Apple toggle is on and models are downloaded, apfel just works.

Apple's full Apple Intelligence setup guide: support.apple.com/en-us/121115

Geographic note: Apple Intelligence is blocked in China mainland (both device purchase location and Apple Account Country/Region matter). Hong Kong, EU, and most other regions are supported as of macOS 26.1.