# Kiwix on Apple: a Swift offline reader for ZIM archives

> kiwix-apple is the iOS, iPadOS and macOS build of the Kiwix offline reader, written in Swift and distributed through the App Store and the Mac App Store. It is a thin application shell around libkiwix and libzim, which makes the toolchain setup rather more involved than installing a reader.

**kiwix/kiwix-apple** — Kiwix for iOS, iPadOS & macOS

- Repository: https://github.com/kiwix/kiwix-apple
- Website: https://apple.kiwix.org
- Stars: 798 · Forks: 115
- Language: Swift
- License: GPL-3.0
- Published: 2026-10-20 · Updated: 2026-10-20 · Language: en
- Canonical page: https://hysenlabs.com/projects/kiwix-kiwix-apple

## An offline reader whose unit of content is the ZIM archive

Kiwix is an offline reader for web content, primarily designed to make Wikipedia available offline. The Apple repository, kiwix/kiwix-apple, is the Swift implementation for iOS, iPadOS and macOS.

Everything the app displays comes from a ZIM file. The README describes ZIM as a highly compressed open format with additional metadata, and the whole reader is built around reading one such archive at a time rather than fetching pages from a server. That is the practical difference from an ordinary browser: there is no address bar resolving live URLs, there is a library of downloaded archives instead.

The users are people who travel, teach, work in areas with poor connectivity, or simply want a trustworthy copy of an encyclopedia on the device. For anyone who wants the web itself offline rather than one curated archive, this is the wrong shape of tool.

## ZIM containers versus serving a mirrored site locally

There is a second way to make a site available offline, and it is worth being explicit about the difference, because the two are easy to confuse.

The alternative approach is to mirror a site into a directory of HTML files and serve it from a local web server or open it from disk. No application is involved, and any browser can be pointed at it. What that approach cannot offer is a single compressed container with per-archive metadata, which is exactly what the ZIM format provides according to the README. A compressed container also means one download and one managed file per title rather than a sprawling directory tree that has to be copied around.

The only content pipeline here is a file you obtain, import and read. The trade-off runs the other way from a normal web app: the archive never updates itself, so freshness depends entirely on replacing the file.

## The build starts with brew bundle, localizations.py and xcodegen

The README gives an explicit onboarding sequence for developers, and it starts from a clean macOS machine with Xcode and Homebrew installed. The prerequisites list an Apple Developer account, which the README says does not require membership, Xcode, its command line utilities through `xcode-select --install`, and Homebrew.

After cloning the repository, the project folder is where the work happens:

```sh
 brew bundle
 python localizations.py generate
 xcodegen
```

`brew bundle` installs the dependencies declared in the Brewfile, `localizations.py generate` produces the localization resources, and `xcodegen` creates the Xcode project files. Without the third command there is nothing for Xcode to open, since those project files are not stored in the repository.

To run the app from Xcode you then have to change the Bundle Identifier under Signing and Capabilities and pick a signing certificate and profile. The README also recommends enabling the .editorconfig setting under Xcode settings, Editing, Indentation.

## Xcode project files are generated by git hooks and never committed

The XcodeGen arrangement is unusual and worth understanding before you change anything in the project.

The README states that the Xcode project files are not contained in the repository and are generated automatically as git hooks on post-merge, post-checkout and post-rewrite, configured in `.pre-commit-config.yaml`. Contributors are told plainly that changes to the Xcode project folder will not be tracked by git.

The consequence is that editing project settings in the Xcode interface is a dead end, because the next hook run overwrites it. The instruction is to edit `project.yml` instead, which is one of the top-level entries in the repository alongside App/, Kiwix/, Model/, SwiftUI/, Views/, ViewModel/, Widgets/, Contents/ and Support/.

For newcomers this saves a lot of merge conflict churn on a project file that machines generate. It also means a fresh clone behaves differently from a clone where somebody once opened Xcode by hand.

## CoreKiwix.xcframework pins the libkiwix and libzim version

The app does not implement the ZIM reading itself. The Brewfile installs `CoreKiwix.xcframework`, a bundle that carries libkiwix and libzim for every supported platform and CPU architecture, and the README notes that its version is specified in the Brewfile.

That pinning is the heart of the dependency story. Kiwix compiles on both x86_64 and arm64, and the same binary set runs on either architecture for both iOS and macOS, so the xcframework exists to hold every slice in one place.

If you need a different version, the README describes two published artifacts, a latest release and a nightly built from the `main` branch of both libkiwix and libzim. Switching is a matter of replacing the `CoreKiwix.xcframework` folder at the root of the project with the downloaded and unpacked version. Building it yourself is also possible: the xcframework is produced from the kiwix-build repository, which needs ninja and meson, and the README gives the sequence:

```sh
brew install ninja meson
```

```sh
git clone https://github.com/kiwix/kiwix-build.git
cd kiwix-build
python3 -m venv .venv
source .venv/bin/activate
pip install -e .

kiwix-build --config apple_all_static libkiwix
```

The `apple_all_static` configuration is what produces the multi-platform static bundle for Apple targets, and the Xcode command tools plus an iOS SDK are needed if you want iOS slices in the result.

## Three test schemes, two destinations, and a consent prompt on macOS

Testing is organized into Xcode schemes, and the README names three of them.

The Kiwix scheme holds the unit tests and can run on both iOS and macOS destinations, triggered from the Product menu with the usual keyboard shortcut. UITests_iOS contains the iOS UI automated tests and requires an iOS destination to be selected beforehand, while UITests_macOS covers the macOS UI tests with macOS as the destination. The README warns that the macOS UI tests might require enabling Automation in Settings and granting admin consent, which is a real friction point in a locked-down environment.

The repository layout backs this up. Besides Tests/, there are separate UITests_common/, UITests_iPad/, UITests_iPhone/ and UITests_macOS/ directories, so UI coverage is split per platform rather than shared, and the CI and CD workflows are configured in `.github/workflows/` with a separate badge for each.

The project also ships a privacy manifest, `PrivacyInfo.xcprivacy`, and a SwiftLint configuration at `.swiftlint.yml`, which tells you linting and privacy declarations are part of the normal contribution loop rather than an afterthought.

## Video inside ZIM files only gets guaranteed support from 3.4.0

The known-bugs section is short and blunt. ZIM files that include video content work properly only from Kiwix version `3.4.0`, from iOS/iPadOS `17.0` and from macOS `14.0`. With older versions of Kiwix or older operating systems, videos might work, but full support is not guaranteed and the README says those bugs will not be investigated further.

The stated reason is the lack of support, until recently, for the open video formats used in ZIM files. That is a content-side limitation rather than a bug in the reader, which is why it cannot simply be fixed in this repository.

If your use case depends on video, that floor is the first thing to check. If it does not, the constraint is irrelevant, and the archive format itself is the only real constraint.

## App Store distribution, a three-version support window and GPL-3.0

Distribution is deliberately narrow. The README says the apps are made available primarily through the App Store and the Mac App Store, and that the macOS version can also be downloaded directly as a .dmg from the Kiwix download server.

The support policy is equally concrete: most recent versions of Kiwix support the three latest major versions of the operating systems, either iOS or macOS, while older versions of the app remain downloadable for older macOS and iOS releases on the Mac App Store. That is the mechanism by which users on an ageing device keep a working build, and it is also why the direct download exists alongside the store listing.

The repository is not archived, and the last push was on 2026-10-17. Releases move in step: 3.17.1 on 2026-09-22, 3.17.0 on 2026-09-20 and 3.16.1 on 2026-07-22.

The licence is GPL-3.0. For an application distributed through the App Store, that matters less than it does for a library you link into, but source availability and the licence notice obligations still follow the code. Anyone shipping a modified build should have their own counsel read what the GPL-3.0 terms require in that context, and note that the core reading engine, libkiwix and libzim, is licensed separately upstream.

## Conclusion

People who want Wikipedia or another site available offline on iPhone, iPad or Mac should adopt kiwix-apple if they are comfortable granting storage access and downloading a large ZIM file, and if they live inside the three most recent OS versions the project supports. Anyone who needs a general purpose offline browser, live web content, or a supported build for an older macOS release should look at the direct .dmg download instead. Before committing, verify the ZIM download size for your chosen title, confirm that your macOS or iOS version is inside the support window, and check whether the video behaviour you need requires Kiwix 3.4.0 or newer, since the README says older versions lack guaranteed video support.

## FAQ

### What does Kiwix for iOS and macOS do?

It is an offline reader for web content, primarily built to make Wikipedia available without a network connection. It reads archives in the ZIM format, described in the README as a highly compressed open format with additional metadata.

### How do I install the Kiwix app on iPhone or Mac?

The README says the apps are made available primarily via the App Store and the Mac App Store. The macOS version can also be downloaded directly as a .dmg from the Kiwix download server.

### How do I build kiwix-apple from source?

You need Xcode with its command line tools, Homebrew, and an Apple Developer account that does not require membership. After cloning, the README lists the commands `brew bundle`, `python localizations.py generate` and `xcodegen`, the last of which generates the Xcode project files.

### Can I run Kiwix on an older version of macOS or iOS?

Most recent versions support the three latest major OS versions, and older versions of Kiwix remain downloadable for older macOS and iOS releases on the Mac App Store. Video inside ZIM files is only guaranteed from Kiwix 3.4.0 with iOS 17.0 or macOS 14.0.

### What is CoreKiwix.xcframework and how do I change its version?

It is the bundle of libkiwix and libzim for all supported platforms and CPU architectures, and the Brewfile pins its version. To use another build you replace the CoreKiwix.xcframework folder at the root of the project with the downloaded and unpacked version, or build it yourself from the kiwix-build repository with `kiwix-build --config apple_all_static libkiwix`.

### Is the kiwix-apple repository still being worked on?

The repository is not archived and the last push was on 2026-10-17. The recorded releases are 3.17.1 on 2026-09-22, 3.17.0 on 2026-09-20 and 3.16.1 on 2026-07-22.

## Sources

- [kiwix/kiwix-apple on GitHub](https://github.com/kiwix/kiwix-apple)
- [License: GPL-3.0](https://github.com/kiwix/kiwix-apple/blob/main/LICENSE)
- [Project website](https://apple.kiwix.org)
- [README](https://github.com/kiwix/kiwix-apple/blob/main/README.md)
- [Releases](https://github.com/kiwix/kiwix-apple/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/kiwix-kiwix-apple