XMPPFramework for iOS and macOS: an Objective-C XMPP stack, and what its 2020 release means for adopters

What XMPPFramework actually implements, and who it is written for

XMPPFramework is a client-side library, not a server. The README describes it as "a core implementation of RFC-3920 (the XMPP standard), along with the tools needed to read & write XML", plus "multiple popular extensions (XEP's)" on a modular architecture. In practice that means your app supplies the UI, the account storage policy and the reconnection policy, while the framework supplies the stream, the stanza model and the extension modules you opt into.

The audience is narrow and stated plainly: "the Mac and iOS development community." The minimum deployment target given in the README is iOS 8.0, macOS 10.9 and tvOS 9.0. The top-level layout matches that: Core/, Authentication/, Categories/, Utilities/, Extensions/, Swift/, plus XMPPFramework.xcodeproj and XMPPFramework.podspec. There is no server component, no command-line client and no daemon.

If you are building a chat feature inside an existing Apple-platform app, this is the shape you want. If you are building a service that needs to speak XMPP to many clients, this is the wrong layer entirely.

Modular XEP extensions and the GCD threading model

The architecture is a core stream plus optional extension modules, which the README calls "a modular architecture, allowing you to plug-in any code needed for the job." Each XEP you need is a module you add and register; the ones you do not need cost you nothing in build surface. The Extensions/ directory holds those modules, and the wiki page "XEPs supported by the XMPPFramework" is where the project points for the supported list.

Concurrency is the other half of the design. The README says the framework is "massively parallel and thread-safe" and "Structured using GCD", with the claim that it "won't block the main thread... at all." That is a design statement about where parsing and I/O run, not a benchmark. What it means for you as an integrator is that callbacks arrive on queues you do not own, so any UI update still has to be dispatched back yourself.

Storage is a third axis. Several modules ship a CoreDataStorage variant, and the README's audit list calls out CoreDataStorage, MUC storage, vCardTemp CoreDataStorage and roster storage as unaudited. If you depend on persisted state, that is the part of the tree with the least API stability guarantee.

Installing XMPPFramework with CocoaPods or Carthage

The README calls CocoaPods "the easiest way to install XMPPFramework." Add the pod to your Podfile. The plain subspec brings in the Objective-C framework only.

pod 'XMPPFramework'

If you also want the Swift additions, use the Swift subspec alongside use_frameworks!. The README shows both lines together.

use_frameworks!
pod 'XMPPFramework/Swift'

After pod install, open the generated .xcworkspace rather than the .xcodeproj, then import the module. Objective-C uses the module import form, Swift uses the plain import.

@import XMPPFramework;

import XMPPFramework

Carthage is the alternative path. Add the GitHub line to your Cartfile, run carthage, and drag the built framework into your Xcode project. The README notes that XMPPFrameworkSwift.framework is a separate artifact you must drag in yourself and then import as XMPPFrameworkSwift in your headers.

github "robbiehanson/XMPPFramework"

For a first real use, the project does not put a connection walkthrough in the README. It points to two wiki pages instead: "Getting started using XMPPFramework on iOS" and "Getting started using XMPPFramework on Mac OS X", plus an "Overview of the XMPP Framework" page. Those wiki pages are where the first connection, authentication and roster steps are documented. Nothing in the README describes a rollback procedure for a failed install or a downgrade path between major versions.

The unaudited modules list is the real limitation

The migration notes from 3.7 to 4.0 are unusually candid. The goal was to improve "the ergonomics and safety when used with Swift", and the project states that "The process is still not complete". Objective-C projects should mostly need no changes; pure Swift projects will need "Many (simple) changes", largely because of the new nullability annotations.

Then comes the part worth reading twice. The README lists modules that "still need an audit" and warns that "their API may contain breaking changes in future releases." That list includes XEP-0191 Blocking, XEP-0199 Ping, XEP-0202 Time, XEP-0136 Archiving, XEP-0115 Capabilities, XEP-0045 MUC, XEP-0054 vCardTemp, XEP-0016 Privacy, XEP-0012 Last Activity, XEP-0009 RPC, Roster, XMPPGoogleSharedStatus, FileTransfer, CoreDataStorage and BandwidthMonitor. Several of those are the modules a real messaging app reaches for first.

So the honest framing is this: the core is audited, the periphery is not, and the project says so in its own README. Treat any module on that list as an API you may have to rework. The README also notes that XMPPPresence's intShow became showValue as an XMPPPresenceShow enum, warning in 4.0 and removed in 4.1, which is the kind of deprecation window you should expect elsewhere.

There is a second limitation that is simply time. The last push to master was on 2020-12-31, the same date as the 4.1.0 release. The repository is not archived, but a five-year gap between the last push and now is the fact that should drive your risk assessment, not the star count or the badge row.

XMPPFramework compared with a Matrix client stack

The comparison people reach for is XMPP against Matrix, and the difference is architectural rather than cosmetic. XMPP, per the README, is RFC-3920: a decentralized protocol where a client connects to a server, and servers federate. XMPPFramework gives you the client end of that, in Objective-C, with XEP modules layered on top.

Matrix takes a different route: state is modelled as a replicated event graph that servers synchronize, and clients typically talk to a homeserver over an HTTP API rather than holding a long-lived XML stream. That changes what a client library has to do. With XMPPFramework you are responsible for stream lifecycle, reconnection and stanza handling; with a Matrix client SDK the sync loop and room state model are largely provided by the library.

Neither is strictly better. XMPP's extension model means you can implement exactly the XEPs your product needs and ignore the rest, which XMPPFramework's plug-in architecture mirrors. Matrix's model means state resolution is defined by the protocol rather than by each client's handling of presence and roster stanzas. If your team already runs XMPP infrastructure, the Matrix comparison is mostly academic; if you are choosing greenfield and your team is Swift-first, the amount of client-side state management you inherit is the deciding factor.

Licence, maintenance and the cost of upgrading

The README carries a BSD-3-Clause badge, and the repository root contains copying.txt. GitHub reports the licence as NOASSERTION, meaning the platform's classifier did not match a standard identifier. Read copying.txt and the badge together before you rely on either; this is a description of what the repository states, not legal advice.

BSD-3-Clause is permissive: it does not require you to open your app's source. That matters here because XMPPFramework is a library you link into a proprietary client. The clause you should actually read is the third one, about not using contributor names to endorse your product.

Upgrade cost is where the project's own documentation is most useful. The 3.7 to 4.0 migration is documented as mostly free for Objective-C and non-trivial for Swift, driven by nullability annotations. The 4.0 to 4.1 step is smaller: the README says intShow's deprecation warning becomes a removal in 4.1. Beyond that, the release list stops at 4.1.0 on 2020-12-31, so there is no documented 5.x migration path. Budget for the possibility that you are adopting a frozen API surface rather than one that will evolve under you. The README's contributing section notes that CocoaPods and Carthage are both needed to work on tests, which tells you the test setup is heavier than the library itself.

Editorial conclusion

Adopt XMPPFramework if you are shipping an Objective-C or Swift iOS/macOS client today and need RFC-3920 plus the common XEPs without writing stanza parsing yourself. Do not adopt it if you need a server, a cross-platform client, or a library that receives security fixes on a predictable cadence: the last push was on 2020-12-31. Before committing, verify that the specific XEP module you need is not on the README's list of unaudited modules, and read XMPPFramework.podspec to confirm which subspecs your build will pull in.

Frequently asked questions

Official sources

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