--- url: https://lettuceai.app/docs/installation title: "Installation — LettuceAI" description: "Install LettuceAI on Android, Arch Linux, Debian and Ubuntu systems, build a Flatpak locally, or build it from source for desktop and mobile development." --- Menu # Installation LettuceAI is available as an Android app, desktop release assets, Arch Linux AUR packages, a Debian-style APT repository, and a Flatpak manifest you can build locally. Contributors can also build it from source for desktop, Android, and iOS. ## Choose a Path - Use the Android release if you want the mobile app on a phone or tablet. - Use the AUR package if you are on Arch Linux or an Arch-based distribution. - Use the APT repository if you are on Debian, Ubuntu, or a compatible derivative and want updates through `apt`. - Use the Flatpak manifest if you want a sandboxed Linux install that works across distributions. The manifest currently ships in the repository as a local build path. - Build from source if you are contributing, developing locally, or need a custom desktop or mobile build. ## Android App The Android app is distributed as a standalone APK. Download the latest release from the [downloads page](/download) or from GitHub Releases. 1. Download the APK file to your Android device. 2. Open the APK file from your file manager or browser downloads. 3. Allow installation from unknown sources if Android prompts you to do so. 4. Finish installation and launch LettuceAI. Android Requirements Android 12 or higher is required. Keep several gigabytes of free storage available for chats, assets, downloaded models, voices, and generated media. ## Desktop Release Assets Desktop releases are published for Windows, macOS, and Linux. If you do not want to build from source, use the matching installer or package for your platform. - Windows: use the published `.msi` installer or`-setup.exe` package for the CPU, Vulkan, or CUDA variant. - macOS: use the published `.dmg` installer for the matching architecture and rendering path. - Linux: use the AUR or APT repository instructions below if you want package-manager installs, or download the published `.deb` or release tarball assets directly from GitHub Releases. ## Arch Linux and AUR LettuceAI publishes separate AUR packages for CPU, Vulkan, and CUDA variants. Choose exactly one package for a system. - `lettuceai-bin`: default CPU build - `lettuceai-vulkan-bin`: Vulkan build for AMD, Intel, or NVIDIA systems with a working Vulkan stack - `lettuceai-cuda-bin`: CUDA build for NVIDIA systems with the CUDA stack installed ### Install with yay ``` # CPU yay -S lettuceai-bin # Vulkan yay -S lettuceai-vulkan-bin # CUDA yay -S lettuceai-cuda-bin ``` ### Install with makepkg ``` # Example: CPU package git clone https://aur.archlinux.org/lettuceai-bin.git cd lettuceai-bin makepkg -si ``` AUR Variant Guidance Install only one LettuceAI AUR package at a time. The packages provide the same application and are marked as conflicting variants. ## Debian, Ubuntu, and Other APT-Based Systems LettuceAI publishes a signed APT repository with separate roots for CPU, Vulkan, and CUDA builds. This lets Debian and Ubuntu users install and update LettuceAI through `apt`. ### CPU Repository ``` curl -fsSL https://lettuceai.github.io/app/debian-repo-public.asc | sudo gpg --dearmor -o /usr/share/keyrings/lettuceai-archive-keyring.gpg echo "deb [signed-by=/usr/share/keyrings/lettuceai-archive-keyring.gpg arch=amd64] https://lettuceai.github.io/app/apt/cpu stable main" | sudo tee /etc/apt/sources.list.d/lettuceai.list sudo apt update sudo apt install lettuceai ``` ### Vulkan Repository ``` curl -fsSL https://lettuceai.github.io/app/debian-repo-public.asc | sudo gpg --dearmor -o /usr/share/keyrings/lettuceai-archive-keyring.gpg echo "deb [signed-by=/usr/share/keyrings/lettuceai-archive-keyring.gpg arch=amd64] https://lettuceai.github.io/app/apt/vulkan stable main" | sudo tee /etc/apt/sources.list.d/lettuceai.list sudo apt update sudo apt install lettuceai ``` ### CUDA Repository ``` curl -fsSL https://lettuceai.github.io/app/debian-repo-public.asc | sudo gpg --dearmor -o /usr/share/keyrings/lettuceai-archive-keyring.gpg echo "deb [signed-by=/usr/share/keyrings/lettuceai-archive-keyring.gpg arch=amd64] https://lettuceai.github.io/app/apt/cuda stable main" | sudo tee /etc/apt/sources.list.d/lettuceai.list sudo apt update sudo apt install lettuceai ``` ### Direct .deb Installation If you only need a one-off install and do not want to add the APT repository, you can install the published `.deb` asset directly. ``` # Example: install a downloaded CPU package sudo apt install ./lettuceai-linux-x86_64-cpu.deb ``` APT Variant Guidance Use only one LettuceAI APT source at a time. The CPU, Vulkan, and CUDA repositories are intentionally split so package managers do not treat incompatible builds as interchangeable candidates. ## Flatpak (Local Build) The repository ships a Flatpak manifest at `flatpak/com.lettuceai.app.yml` and a helper script at `scripts/flatpak-local-build.sh`. This lets you build a sandboxed Linux package on your own machine and install it through `flatpak`. There is no hosted Flathub or remote repository yet, so this is a build-from-manifest workflow rather than a one-line install. ### Prerequisites - `flatpak` and `flatpak-builder` installed - The Flathub remote configured for your user - GNOME platform and SDK runtimes plus the Rust and Node SDK extensions (the build script will install missing dependencies from Flathub on first run) ``` # From the mobile-app repository root bash scripts/flatpak-local-build.sh # Install the produced bundle flatpak install --user ./lettuceai.flatpak # Run it flatpak run com.lettuceai.app ``` Flatpak Status Flatpak support is currently a local build path. The manifest and helper script are in the repository, but there is no published Flathub or remote Flatpak repository yet. ## Build from Source The project uses Bun, Tauri v2, React, and Rust. Most contributors should use the wrapper commands in the repository rather than invoking raw Tauri commands directly. The wrappers encode platform-specific fixes, toolchain setup, and build-time workarounds. ### Prerequisites - Bun 1.1 or newer - Rust and Cargo - Android Studio and Android SDK components for Android work - Xcode and the iOS toolchain for iOS work on macOS - Platform-native runtime dependencies such as WebKitGTK on Linux and eSpeak NG for Kokoro TTS on desktop ### Clone and Install Dependencies ``` git clone https://github.com/LettuceAI/mobile-app.git cd mobile-app bun install ``` ### Common Commands ``` # Frontend only bun run dev bun run build # Desktop (default Tauri flow) bun run tauri dev bun run tauri build # Linux / Wayland fallback if the normal Tauri run has WebKit issues bun run tauri:dev:webkit-safe bun run tauri:build:webkit-safe # Desktop with NVIDIA CUDA llama.cpp acceleration (auto-detect local GPU arch) bun run tauri:dev:cuda:auto bun run tauri:build:cuda:auto # Desktop with Vulkan llama.cpp acceleration bun run tauri dev --features llama-gpu-vulkan bun run tauri build --features llama-gpu-vulkan # Desktop with Metal acceleration on macOS bun run tauri:dev:metal bun run tauri:build:metal bun run tauri:build:macos # Android bun run tauri:android:init bun run tauri:android:dev bun run tauri:android:build # iOS (macOS only) bun run tauri:ios:init bun run tauri:ios:dev:ready bun run tauri:ios:build:ready # Quality checks bunx tsc --noEmit bun run check cd src-tauri && cargo fmt && cargo check ``` ### Which Desktop Command Should You Use? - Use `bun run tauri dev` and `bun run tauri build`for standard desktop development. - If Linux WebKit or Wayland behavior is unstable, use the`webkit-safe` wrappers. - Use the CUDA wrappers on NVIDIA systems. These wrappers auto-detect CUDA architecture information and apply the Linux position-independent-code flags the project expects. - Use the Vulkan feature flag path when you want cross-vendor GPU acceleration through Vulkan. - Use the Metal wrappers on macOS when building the Apple GPU-accelerated variant. Windows Contributors The repository also includes native Windows wrapper scripts under`scripts/windows/` in both `.cmd` and PowerShell form. ``` .\scripts\windows\desktop-dev.ps1 .\scripts\windows\desktop-build.ps1 .\scripts\windows\android-init.ps1 .\scripts\windows\android-dev.ps1 .\scripts\windows\android-build.ps1 .\scripts\windows\check.ps1 ``` ``` scripts\windows\desktop-dev.cmd scripts\windows\desktop-build.cmd scripts\windows\android-init.cmd scripts\windows\android-dev.cmd scripts\windows\android-build.cmd scripts\windows\check.cmd ``` ## Desktop Runtime Dependencies ### eSpeak NG for Kokoro TTS Desktop Kokoro TTS phonemization shells out to a system-installed`espeak-ng`. If it is not available on `PATH`, the app will surface the same guidance at runtime. ``` # Ubuntu / Debian sudo apt install espeak-ng # Fedora sudo dnf install espeak-ng # Arch / Manjaro sudo pacman -S espeak-ng ``` ``` # Windows winget install eSpeak-NG.eSpeak-NG ``` ``` # macOS brew install espeak-ng ``` You can also point the app at a custom eSpeak NG binary or data directory through the TTS settings panel. ## Android Development Environment Android development expects Android Studio, the SDK, platform tools, command-line tools, and the NDK to be installed. The main source of build failures is environment mismatch between your interactive shell and the non-interactive shell used by build tooling. ### Environment Variables ``` export ANDROID_SDK_ROOT="$HOME/Android/Sdk" export ANDROID_HOME="$ANDROID_SDK_ROOT" export ANDROID_NDK_HOME="$ANDROID_SDK_ROOT/ndk/" export NDK_HOME="$ANDROID_NDK_HOME" export PATH="$ANDROID_SDK_ROOT/platform-tools:$ANDROID_SDK_ROOT/emulator:$ANDROID_SDK_ROOT/cmdline-tools/latest/bin:$PATH" bash -lc 'echo ANDROID_HOME=$ANDROID_HOME; echo ANDROID_SDK_ROOT=$ANDROID_SDK_ROOT; echo ANDROID_NDK_HOME=$ANDROID_NDK_HOME; echo NDK_HOME=$NDK_HOME' ``` ``` $env:ANDROID_SDK_ROOT = "$HOME\Android\Sdk" $env:ANDROID_HOME = $env:ANDROID_SDK_ROOT $env:ANDROID_NDK_HOME = "$env:ANDROID_SDK_ROOT\ndk\" $env:NDK_HOME = $env:ANDROID_NDK_HOME $env:PATH = "$env:ANDROID_SDK_ROOT\platform-tools;$env:ANDROID_SDK_ROOT\emulator;$env:ANDROID_SDK_ROOT\cmdline-tools\latest\bin;$env:PATH" ``` ### Android Project Initialization ``` bun run tauri:android:init ``` ### Android Kokoro eSpeak Bundle Android builds require the Kokoro eSpeak native bundle. The Rust build script enforces this and will refuse to build without it. There are four supported ways to provide the bundle: 1. Let the build script download the default published bundle automatically. 2. Build the bundle locally with the helper script. 3. Point the build at a custom remote bundle URL. 4. Reuse already-installed bundle files under the generated Android project. ``` # Build a local bundle ANDROID_SDK_ROOT=$ANDROID_HOME bash scripts/build-espeak-android-bundle.sh export KOKORO_ESPEAK_ANDROID_BUNDLE_PATH=/tmp/kokoro-espeak-android-bundle.tar.gz bun run tauri:android:dev ``` ``` # Or override with a remote bundle export KOKORO_ESPEAK_ANDROID_BUNDLE_URL=https://example.com/kokoro-espeak-android-bundle.tar.gz ``` ### Android Build and Run ``` # Run on emulator or attached device bun run tauri:android:dev # Build APK bun run tauri:android:build ``` Android Troubleshooting If Android Rust builds fail inside `whisper-rs-sys`, verify your NDK and CMake setup first. If Cargo registry outputs become wedged, clean the Tauri build tree with `cargo clean --manifest-path src-tauri/Cargo.toml` and retry. ## iOS Development Environment iOS development is macOS-only. You need Xcode, the Xcode command-line tools, CocoaPods, and an iOS-compatible ONNX Runtime package that includes the CoreML execution provider. ``` xcode-select --install export ORT_LIB_LOCATION=/absolute/path/to/onnxruntime/ios/libs bun run tauri:ios:init bun run tauri:ios:dev:ready bun run tauri:ios:build:ready ``` The project wrappers assume ONNX Runtime slices have already been prepared for iOS. Set `ORT_LIB_LOCATION` before building. ## macOS Distribution Builds To build a native macOS application bundle and DMG installer on macOS, use the dedicated macOS wrapper. ``` bun run tauri:build:macos ``` The generated artifacts are placed under: - `src-tauri/target/release/bundle/macos/*.app` - `src-tauri/target/release/bundle/dmg/*.dmg` ## Notes - Prefer repository wrapper commands over raw tool invocations where the repo already provides a wrapper. - On Linux, use the WebKit-safe wrappers if the default Tauri window path behaves poorly under Wayland. - On desktop, install `espeak-ng` before debugging Kokoro TTS issues. - On Android, keep your shell environment consistent across interactive shells and `bash -lc` build invocations. - For package-manager installs, choose one hardware variant and stay on that variant unless you intentionally want to switch builds. [ PreviousIntroduction ](/docs)[ NextQuick Start ](/docs/quickstart)