paho.mqtt.android: an MQTT client for Android in maintenance mode

The project states its own status plainly

paho.mqtt.android is an MQTT client library written in Kotlin, created to provide reliable open source implementations of open and standard messaging protocols for machine to machine and Internet of Things applications. The README spends a paragraph on why MQTT exists as a protocol, pointing at the physical and cost constraints of device connectivity and at the goal of decoupling devices from applications.

Then it says something more useful for anyone evaluating the project: the status is maintenance mode. Issues are ignored, but pull requests are not. The instruction to anyone who needs something done is to submit a pull request.

That is a specific kind of promise. You get a maintained codebase in the sense that someone still merges patches, and you get no support in the sense that nobody is triaging your problem report. For an internal mobile project where a team is prepared to contribute fixes, that is a workable arrangement. For a product team that expects a maintainer to investigate a bug report, it is not, and the difference is worth settling before you build on it.

The repository is not archived, and the last push was on 2026-10-22, so the code is not frozen. The licence is Apache 2.0, with the full licence text included in the readme.

The dependency comes from JitPack

There is no mention of a standard package repository in the documentation. Instead, the readme points at JitPack, with the details on the JitPack project page for hannesa2/paho.mqtt.android.

Adding the repository to your Gradle build looks like this:

allprojects {
  repositories {
    ...
    maven { url 'https://jitpack.io' }
  }
}

And the dependency itself:

dependencies {
  implementation "com.github.hannesa2:paho.mqtt.android:$latestVersion"
}

The coordinate is the GitHub style `com.github` group, which is what JitPack uses, and the version is left as a placeholder that you substitute with the release you want. The repository contains a `jitpack.yml` file at the root, which is the configuration JitPack reads when it builds your artifact.

The practical consequence for a team is that the build now depends on a repository that builds the library on demand from the GitHub source rather than serving a binary from a conventional repository. That has two consequences. It means the artifact you get is tied to the commit that was requested, and it means the availability of the library depends on JitPack and GitHub being reachable at build time, which is a different risk profile from a Maven Central dependency with a published checksum.

The repository also has a `gradle.properties`, `build.gradle.kts` and `settings.gradle.kts`, so the library itself is built as a Gradle Kotlin DSL project.

Version 4 swapped the foreground service for WorkManager

The most consequential change in the library is the one that separates the 4.x line from everything before it, and it is a background behaviour change rather than an API change.

In 4.x, the client does not need a foreground service. The documented advantages are that it does not use `android.permission.SCHEDULE_EXACT_ALARM`, which drains the battery, and that it uses `androidx.work:work-runtime-ktx` to receive messages during device sleep. That second point is the interesting one. A client that keeps a socket open for a year has to survive Doze and app standby, and the modern Android way to get scheduled work done in that state is WorkManager rather than an exact alarm plus a persistent notification.

The trade is worth naming explicitly. A foreground service gives you a running process with a visible notification and a very short path to delivery, at the cost of a permanent notification and the permissions that go with it. WorkManager gives you deferrable, battery-aware execution with no notification, at the cost of latency that is not under your control. For an MQTT client, that means the 4.x behaviour is better for apps that tolerate delayed delivery and worse for apps that need a message processed within seconds of arriving.

The 4.x documentation lists only those two advantages, so if your requirement is precise delivery guarantees, the older model is still the one described in the repository.

The 3.x foreground service path is deprecated but still shown

For the 3.x line the documentation gives the older arrangement explicitly. When you use a 3.x version on Android O or later, you should use it as a foreground service, and the construction is a one-liner on the client object:

val client = MqttAndroidClient(context, uri, clientId).apply {
    setForegroundService(foregroundNotification, 3)
}

The notification is supplied by the application, and the trailing number is the notification identifier the service uses. The section is labelled deprecated, so this is the compatibility path rather than the recommended one, and anyone on 3.x is being told to move to 4.x.

That leaves a migration question for anyone who adopted this library early. A 3.x integration has an application supplied notification, a foreground service declaration, and possibly the exact alarm permission, all of which have to be removed when moving to 4.x and replaced with whatever WorkManager requirements the app already has. The readme does not provide a migration guide, so the work is yours to plan.

The version numbers tell you the shape of the release history. Recent tags are 4.5.1 on 2026-10-05, 3.7-beta2 on 2026-07-01 and 4.6-beta1 on 2026-05-14, so the 3.x line still received a beta after the 4.x line was established, and the 4.x line is where the released versions are now.

A library module with two sample applications

The repository is split into a library module and two sample apps. `serviceLibrary` holds the client itself, while `basicSample` and `extendedSample` show how to use it at two levels of detail. There is also a `test` directory, a `buildSrc` directory for custom Gradle build logic, and a `gradle` directory with the wrapper.

The screenshots infrastructure is unusual enough to mention. Alongside the `screenShotScript` directory there is `screenshotsToCompare14`, which reads as a comparison set for the 4.x line, and the `git-diff-image` directory. That is a test harness that captures screenshots of the sample application and compares them against a reference set, which is a sensible way to catch visual regressions in a client whose whole surface is a notification and a few dialogs.

There is also a `.gitmodules` file, so parts of the tree come in as submodules, and an `.idea` directory with the IntelliJ project files checked in.

For someone reading the code, the practical order is `serviceLibrary` for the API surface, then `basicSample` for the smallest working connection, then `extendedSample` for the fuller feature set. The samples are also the only place the readme implies you will find usage detail, since the documentation itself is kept to a page and a half.

Apache 2.0 terms and what maintenance mode means for you

The licence is Apache 2.0, and the readme includes the licence text with a 2025 copyright line. For a client library that you link into an application you distribute, the Apache grant is the permissive one you would want: no copyleft obligation on your own code, and the patent and trademark clauses are the reason it is often preferred over BSD for a component you intend to ship commercially.

The two samples and the library module in the repository make the delivery model clear. Nothing here is a hosted service, and there is no server component, so the whole cost of running this in production is the MQTT broker you already point it at.

What maintenance mode costs you in practice is a queue of unanswered issues. If a broker changes behaviour, or a new Android release changes background execution rules, the fix arrives when somebody who hits it writes it. The library's own answer is the 4.x rewrite of the background model, which moved the heavy lifting from exact alarms and foreground services onto a platform library that Google maintains.

If you are weighing this against building on the Eclipse Paho Java client directly, or against a broker's own Android SDK, the decisive questions are the same: does your app need message delivery while the device sleeps, and can you accept deferrable delivery for that case. If yes, the WorkManager based 4.x path is the more honest fit for modern Android than a foreground service that shows a permanent notification.

Editorial conclusion

paho.mqtt.android suits an Android team with an existing MQTT broker integration that needs a client library which keeps working without a foreground service and without the exact alarm permission, and that is willing to send patches rather than file issues. It is a poor fit for a greenfield project that needs active support, because the project is explicitly in maintenance mode, and a poor fit if your build cannot resolve artifacts from JitPack. Before you adopt it, read the 4.x background behaviour notes and confirm the WorkManager based delivery fits a background message requirement your app must meet, and check the `serviceLibrary` module for the API surface you need rather than assuming the sample code covers it.

Frequently asked questions

Official sources

1. hannesa2/paho.mqtt.android on GitHub
2. Issues
3. License: Apache-2.0
4. README
5. Releases