wikipedia-ios: Building the Official Wikipedia App for iOS

What wikipedia-ios Is and Who It Is For

wikipedia-ios is the official Wikipedia client for iOS, written primarily in Swift and released under the MIT License. The repository README opens with a one-line description: "The official Wikipedia iOS app." That sentence is the whole pitch, and it is accurate. This is not a library you add to another project, and it is not a general-purpose wiki reader. It is the shipping application, with the same code paths that produce the App Store build.

The audience follows from that. The people who get value here are engineers working on the Wikipedia app itself, and engineers who want a large, real Swift codebase that talks to MediaWiki APIs to study or fork. The repository layout reflects that audience: top-level directories include Wikipedia/, WMF Framework/, WMFComponents/, WMFData/, WikipediaUnitTests/, WikipediaUITests/, and a fastlane/ directory for release automation. There is also a docs/ directory, which the README points to for process and code review norms via docs/process.md.

If you are looking for a drop-in Wikipedia API client, this is the wrong shape of project. The interesting networking and model code lives inside an application target, not behind a published package. You would be extracting code, not importing it.

How the Xcode Project, Schemes and Configuration Fit Together

The build is a standard Xcode project, Wikipedia.xcodeproj, with a set of schemes that each point at a different server environment. The README describes them explicitly. The Wikipedia scheme points to production servers. The Staging scheme points to staging environments and has feature flags set to true, so it displays features that are still in development, and it is pushed to TestFlight as a separate app. The Experimental scheme is for one-off builds that demonstrate early development or prototype features, and it also ships to TestFlight as a separate app.

Switching environments is done in code rather than in a build setting. The README says you adjust the environments by changing the current property of Configuration, located at WMF Framework/Configuration.swift. The Staging scheme offers appsLabsForPCS for the Apps team's staging environment for page content, and betaCluster for most API calls, which the README describes as a more blanket environment setting that also forces the beta cluster for page content on the article view. The beta cluster is also where developers can test sandbox push notifications across wikis, and it is selected by default.

There is a fourth scheme, Local Page Content Service and Announcements, that the README says is used by engineers in Debug mode only. It can point at a locally running mobileapps repository for page content via the localPCS option, and at a locally running wikifeeds repository for the announcements endpoint via localAnnouncements, with all other endpoints going to production. Two more schemes round out the list: RTL, which launches the app in an RTL locale using the -AppleLocale launch argument, and Performance Testing, a duplicate of the Wikipedia scheme that uses the Release configuration in its Run step instead of Debug and is used when the team manually runs performance tests as part of its pre-release checklist.

One structural detail matters if you plan to change shared code: the WMF scheme bundles the app logic shared between the main app and the extensions, which the README names as widgets and notifications. Widgets/, ContinueReadingWidget/ and NotificationServiceExtension/ are separate top-level directories, so a change in shared code can affect more than the main target.

Installing the Toolchain and Running the App for the First Time

The README states that your Xcode version must be at least 16.0, and that you run the setup script from the repository root. It warns specifically that going into the scripts directory and running setup there will not work because of relative paths. So the first command is run from the top level:

./scripts/setup

According to the README, this script assumes Xcode is already installed. It installs Homebrew, SwiftLint and ClangFormat, and it creates a pre-commit hook that uses ClangFormat for linting Objective-C code. Expect it to modify your machine, not just the checkout: Homebrew and the two linters land outside the repository.

If you would rather install the prerequisites yourself, the README lists the required dependencies as Xcode, SwiftLint and ClangFormat. That path skips the pre-commit hook, so you would be responsible for formatting Objective-C yourself.

After setup completes, the README says you should be able to open Wikipedia.xcodeproj and run the app on the iOS Simulator using the Wikipedia scheme and target. The scheme and target selection is the part people get wrong, because the project contains several schemes and the README's instruction is specific: use Wikipedia, not Staging or Experimental, unless you intend to point at a non-production environment.

For tests, the README states that the Wikipedia scheme runs the project's iOS unit tests, triggered with the Cmd+U hotkey or the Product then Test menu action. It also states a precondition that is easy to miss: for the tests to pass, the test device's language and region must be set to en-US under Settings, General, Language & Region. There is a ticket filed to update the tests so they pass regardless of language and region, so this is a known constraint rather than an intended design.

The Setup Script Assumes a Mac and a Working Homebrew Path

The most concrete limitation is platform. The README gives no instructions for Linux, Windows or a container, and the build entry point is an Xcode project that requires Xcode 16.0 or later. If you do not have a Mac with a recent Xcode, there is no documented path to a running app in this repository. That is not a criticism of the project, which is an iOS app by definition, but it does rule out a large set of potential contributors and CI setups.

The setup script is also invasive by design. It installs Homebrew if it is not present, then SwiftLint and ClangFormat, and it writes a pre-commit hook into your checkout. On a machine where Homebrew is managed by someone else, or where installing a Git hook is not acceptable, the script is the wrong tool. The README does acknowledge the alternative: install the three dependencies yourself. What it does not document is how to reproduce the pre-commit hook manually, so a self-managed setup will diverge from the scripted one.

A second failure mode is environmental rather than structural. The README's own troubleshooting instruction is to file a bug report on Phabricator if you encounter issues, which tells you the setup path is not guaranteed to be smooth across machines. Bug reports go to the wikipedia-ios-app-product-backlog and ios-bug-backlog projects, and the README provides a form link with a title prefix of [BUG] and a body template asking for reproduction count, steps, expected and actual results, screenshots, app version, OS versions, device model, device language and whether it is a regression. If you hit a failure, that template is the expected channel, not a GitHub issue.

Finally, the unit tests carry a locale dependency. The README states the test device's language and region must be en-US for the tests to pass, and links a ticket to fix that. On a CI runner configured for another locale, you should expect failures that have nothing to do with your change.

How this differs from Kiwix and other offline readers

The obvious comparison for anyone who wants Wikipedia on a phone without the network is Kiwix, which serves ZIM archives of Wikipedia content for offline reading. The difference in approach is fundamental. wikipedia-ios is a client: the README's scheme documentation is entirely about which server environment the app talks to, from production to the beta cluster to a locally running mobileapps service. Content arrives over the network from MediaWiki APIs.

Kiwix inverts that. The content is a file you download and store on the device, and the reader is a viewer over that file. The trade-off is freshness against availability. A wikipedia-ios build always shows current article content because it fetches from production or staging servers, and it breaks when the network or the API does. A ZIM-based reader keeps working on a plane or in a region with poor connectivity, but the snapshot ages until you fetch a new archive.

There is a practical consequence for contributors too. If your interest is in rendering wiki markup, citation formatting or search over a static corpus, the wikipedia-ios repository is mostly the wrong place to look, because that work happens server-side and arrives as structured responses. If your interest is in client architecture, scheme separation and the interaction between an app target and its extensions, this repository is a much better fit than an offline reader.

Licence, Logging and the Cost of Keeping Up

The repository is MIT licensed, with the licence file at LICENSE.txt and the README listing the MIT License as the project licence. MIT is permissive: it allows reuse in closed products provided the copyright notice and permission notice are preserved. This article does not give legal advice, and anyone shipping a derivative should read LICENSE.txt rather than rely on the one-line summary, because the file is the operative text.

Upgrade cost is shaped by the release cadence visible in the repository. Releases are tagged frequently, with 2026.08.11 tagged on 2026-08-12, 2026.07.31 tagged on 2026-08-03, and 8.2.2 tagged on 2026-07-22. The last push to the main branch was on 2026-08-12. A fork that tracks upstream will be rebasing against a moving target on a roughly weekly rhythm, and because the app shares code with its extensions through the WMF scheme, a change in shared code can ripple into widgets and notifications at the same time.

There is also a logging behaviour worth knowing before you start debugging. The README states that log levels are shortened to emoji: a speaking head for Verbose, a speech balloon for Debug, an information symbol for Info, a warning sign for Warning, and a rotating light for Error. It further states that the app writes only Warning and Error messages to the console in both Debug and Release mode. If you need all messages during troubleshooting, the README says to update the level in Wikipedia/Code/WMFLogging.h to DDLogLevelAll. That is a source edit, not a runtime flag, so it is a change you have to remember to revert.

Editorial conclusion

Adopt wikipedia-ios if you need to read or modify the production client for Wikipedia on iOS, or if you are building a MediaWiki-backed reader and want a reference implementation of the app's scheme and target layout. Do not adopt it if you are not on macOS with Xcode 16.0 or later, or if you want a cross-platform reader: the repository is an Xcode project, and the README documents no Android, web or Linux build path. Before writing code, verify three things: that ./scripts/setup completes, that the Wikipedia scheme builds and runs on the simulator, and that the unit tests pass with the test device's language and region set to en-US, since the README states the tests require that setting. If your change touches Objective-C, check the pre-commit hook that setup installs, because it runs ClangFormat on that code.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes