Back to blog

Jenkins macOS native installer deprecation

Oleg Nenashev
Oleg Nenashev
November 25, 2019

In addition to WAR files and Docker images, the Jenkins project provides native installers for each weekly and LTS release. There are installers available for Linux distributions, Windows, macOS and other operating systems. There are also installers provided by third parties. You can find the list of these installers on the Downloads page.

In this blog post, we announce the upcoming deprecation of the macOS native installer. We will review the replacement options and the rollout plan.


Maintaining installers is a significant maintenance effort for the project because installers require testing and, sometimes, specific platforms and environments for packaging. When installers lose relevance for the majority of the Jenkins audience, we remove them or handover maintenance to third parties on other areas. For macOS, there are currently two types of packages: native installers with GUI for desktop versions and Homebrew packages. Since Homebrew is now a defacto standard package manager for macOS users, from the Jenkins standpoint it made sense to deprecate the native installers.

Why now? There is ongoing work on automating Jenkins Core releases within the Jenkins infrastructure. Long story short, we are moving Jenkins release pipelines to Kubernetes on Microsoft Azure. This environment does not offer macOS machines that are needed to produce native installers. If you are interested to know more, there will be a How Jenkins Builds and Delivers Jenkins in the Cloud talk presented by Olivier Vernin at DevOps World | Jenkins World 2019 Europe in Lisbon (use the JWFOSS code for a 30% discount!).

We could have used an external service for building macOS installers, but it would have added an additional point of failure and implementation/maintenance overhead. So we discussed it in the developer mailing list and agreed that it is better to just deprecate and then remove the packages.

Replacing native installers

In the case of macOS, there are two main alternatives available: managing the service manually or migrating to Homebrew packages. Before doing a migration, we highly recommend backing up your instance.

Managing Jenkins with WAR file on macOS

If your Jenkins instance was previously set up with a native installer, to update Jenkins it will be enough to replace the jenkins.war file in the installation directory and restart the instance. The services will keep running as it was configured before the migration. The default installation directory is /Applications/Jenkins/jenkins.war

Managing Jenkins with Homebrew

Installing Jenkins with Homebrew is a way to go for those who want to install Jenkins using a package manager. There are two Homebrew formulas for Jenkins: jenkins for Weekly releases and jenkins-lts for LTS ones. These packages are supported by a third party (Homebrew community), and they may be not as frequently updated as packages supported by the Jenkins project directly.

Before doing a migration from macOS Native installers to HomeBrew, please make sure to backup your Jenkins instance. There are no automatic migration tools available, and the installation may corrupt your JENKINS_HOME or service configuration files in edge cases.

If you switch to Homebrew, you will need to properly migrate the JENKINS_HOME data to the new location. We do not provide an official migration guide, but it is possible to find some guidelines on the Web.

Sample commands:

  • Install the latest Weekly version: brew install jenkins

  • Start the Jenkins service: brew services start jenkins

  • Restart the Jenkins service: brew services restart jenkins

  • Update the Jenkins version: brew upgrade jenkins

For more information see the documentation for Homebrew packages on the macOS Download pages.

Rollout plan

  1. macOS native packaging is considered as deprecated starting from Jenkins 2.206 and Jenkins LTS 2.204.1

  2. For Jenkins Weekly macOS native packaging will be removed with the switch to the new Jenkins release flow. The exact date is to be determined.

    • After the change, there will be no macOS native installers produced for new Jenkins Weekly releases

    • Releases for previous versions will be available in this archive

  3. For Jenkins LTS macOS will be removed with the switch to the new Jenkins release flow in the LTS baseline. This change will happen only after the deployment of the new release flow in Jenkins Weekly.

    • After the switch, there will be no macOS native installers produced for new Jenkins LTS releases

    • Releases for previous versions will be available in this archive

See the discussion on the developer mailing list for more information.

Questions and feedback

If you have any questions or want to provide feedback, please use the developer mailing list thread mentioned above Platform SIG channels (chat, google group). Any feedback will be much appreciated because we plan more installer/ and platform deprecations in the future.

About the author

Oleg Nenashev

Oleg Nenashev

Jenkins core maintainer and board member, open source software and open hardware advocate, TOC member in the Continuous Delivery Foundation. Oleg started using Hudson for Hardware/Embedded projects in 2008 and became an active Jenkins contributor in 2012. He maintains Jenkinsfile Runner, contributes to several Jenkins SIGs and outreach programs (Google Summer of Code, Hacktoberfest) and organizes Jenkins meetups in Switzerland and online. Oleg works on the WireMock project and WireMock Cloud community at WireMock Inc.