Build a signed iOS app on Linux. The Mac is needed only to compile the asset catalog.
lipa compiles Swift sources with the open-source Swift toolchain against a Darwin SDK built from your own copy of Xcode, signs the bundle with rcodesign, and packages an IPA that App Store Connect accepts. Upload stays with your publishing tool.
The one Mac-only tool is actool, which compiles the asset catalog. lipa prepare --mac <host> runs it over any shell transport you already have and caches the result on the Linux machine.
- Linux x86_64, Bun 1.4 or the release binary.
lipa setuppins the tools for x86_64 only. - A Mac with Xcode, reachable with
sshwithout a password, or with any command that opens a shell on it.docs/mac.mdcovers the Mac side. - A distribution certificate, its private key and an App Store provisioning profile for the bundle id.
The Xcode SDK license covers Apple hardware only. lipa never ships the SDK and never uploads it anywhere: it builds one from the copy of Xcode you already have, and the license question stays with you.
curl -fsSL https://github.com/tapeo/lipa/releases/latest/download/install.sh | sh
lipa setupFrom a checkout:
bun install
bun run bininstall.sh puts the CLI in ~/.lipa/bin, so add that directory to PATH. The pinned tools live under ~/.lipa/tools; lipa adds the Swift toolchain to PATH for xtool itself, so it does not have to be exported in your shell.
lipa update replaces that binary with the latest release, after checking it against the checksums.txt of the release. lipa update --check only reports whether a newer version exists, and it works from a checkout as well.
Each command assumes the one before it. prepare and build run the earlier steps themselves when something is missing.
# once per machine: Swift, xtool and rcodesign at pinned versions
lipa setup
# once per Xcode, from a local download
lipa sdk --xcode ~/Downloads/Xcode.xip
# or from the Mac itself
lipa sdk --mac macbook
# once per signing identity
lipa signing import --cert cert.pem --key key.pem --profile App.mobileprovision
# after the assets, the SDK or the toolchain changed: compile ahead of the build
lipa prepare --mac macbook
# every build
lipa build --build 42 --out build/App.ipa
# before uploading
lipa inspect build/App.ipa
# try it on a device, over USB or a VPN address such as a tailnet name
lipa run --device iphonelipa build reads project.yml from an XcodeGen project: target, bundle id, team, deployment target, sources, resources, packages, Info.plist, entitlements and the app extensions the target embeds. It writes nothing into the project except build/.
lipa doctor says which step is missing and which command to run.
lipa run installs its device helper on the first use, about 300 MB under ~/.lipa/tools/device, or ahead of time with lipa setup --only device. It also needs a RemotePairing record for the device: docs/cli.md has the one command that makes it. prepare and build never install it.
--mac <host> runs ssh <host>, so user, port, key and jump host belong in ~/.ssh/config:
Host macbook
HostName 192.168.1.10
User me
IdentityFile ~/.ssh/id_ed25519
lipa doctor --mac macbookdoctor checks the connection, macOS, the selected Xcode, the Xcode license, actool and the iOS SDK on the Mac against the one on Linux, and prints the command that fixes whatever is missing. docs/mac.md has the Mac side: Remote Login, xcode-select and the license.
ssh runs without a password prompt. When the key is missing the command fails at once with remote_unreachable instead of waiting.
--via <command> replaces ssh for a machine reachable another way, for example through a wrapper of your own. It runs <command> '<script>' and passes stdin and stdout unchanged.
project.yml ──► wrapper SwiftPM package ──► xtool + Swift for Linux
│ │
Support/Prebuilt ◄── actool on a Mac ▼
~/.lipa/cache ────────────────► assemble App.app: plist keys, resources, strip
│
▼
patch LC_BUILD_VERSION, sign with rcodesign, zip
- The wrapper package lives in
~/.lipa/work/<bundle-id>/package-<hash>and points at the project sources with a symlink, one link per sources entry. The project stays an XcodeGen project. - An app extension is a target of
project.ymlthat the app depends on withtarget:. lipa builds it, puts it inPlugIns/, signs it with its own profile and compiles its string catalogs. LC_BUILD_VERSIONcarries the deployment target in its SDK field, and App Store Connect rejects that as an old SDK. lipa patches it to the SDK version it linked against, before signing.- Signing needs
cert.pem,key.pemand a profile whoseapplication-identifiermatches the project, plus one profile per extension bundle id.lipa doctorchecks them against each other. preparecompiles into that package and does not sign.buildcalls it, then assembles, signs and zips, so a warm build takes seconds.actooloutput is cached per bundle id with a hash of the asset catalog and the SDK version. A stale cache stops the build withprebuilt_stale, it does not build something different from what the Mac would.
Everything lipa owns is under ~/.lipa: tools/, signing/, cache/, work/, symbols/. Keys are mode 600, directories mode 700. The IPA goes where --out says, build/<app>.ipa by default.
| Command | What it does |
|---|---|
lipa setup |
Installs Swift, xtool and rcodesign at pinned versions, sha256 checked. --only device adds the device helper |
lipa sdk --xcode <path> |
Builds and installs the Darwin SDK from Xcode.app or Xcode.xip |
lipa sdk --mac <host> |
Copies the SDK parts of Xcode.app from a Mac, installs the SDK, deletes the copy |
lipa signing import |
Stores the certificate, the key and the profile for a bundle id |
lipa prepare |
Compiles the app and refreshes the prebuilt cache, without signing |
lipa build |
Prepare, assemble, patch, strip, sign, zip, inspect |
lipa inspect <ipa> |
Executable mode, plist keys, SDK, signature, profile, extensions, string catalogs |
lipa doctor |
Tools, SDK, workspace, cache, signing and the Mac in one report |
lipa run |
Build for development, install on a device, launch and follow its logs |
prepare and build take --mac <host>, --via <command>, --update for the dependencies and --clean for a full recompile. prepare also takes --import <dir> for an actool output produced elsewhere. build takes --signing app-store|development and --configuration release|debug, and run builds debug unless --configuration release says otherwise.
Every command answers JSON without a terminal or with --json, and exit codes are stable: 2 usage, 3 missing tool or Xcode, 4 stale prebuilt cache, 5 SDK mismatch, 6 signing, 7 bad IPA, 8 Mac unreachable, 9 device unreachable.
- XcodeGen only. Projects without
project.ymlare not read. - Flutter is out:
flutter build iosrefuses to run on Linux. - No dSYM: the Linux toolchain has no
dsymutil. lipa keeps the unstripped binary, with the same UUID, in~/.lipa/symbols. - No storyboards and no Core Data models. String catalogs are compiled on Linux: plain strings, plural and device variations, plural substitutions.
- App extensions build from their own target, but not with an asset catalog of their own.
swift packagedependencies compile on Linux as they are. A package that needsactool,ibtoolormomcfor its own resources does not build.- The Mac is needed for
actoolonly.lipa sdk --xcodebuilds the SDK from a local copy of Xcode,lipa sdk --mactakes it from the Mac.
MIT.