← Guides

Installing Jenkins on macOS

jenkinsmacoshomebrewdockerci-cddevopsinstallation-guidetroubleshooting July 2026

Installing Jenkins on macOS

1. Install Homebrew (skip if you already have it)

Check first:

brew -v

If that fails, install it:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

2. Install Java

Jenkins needs a JDK to run. Java 17 or 21 works well:

brew install openjdk@17

Then link it so macOS can find it:

sudo ln -sfn /opt/homebrew/opt/openjdk@17/libexec/openjdk.jdk /Library/Java/JavaVirtualMachines/openjdk-17.jdk

On Intel Macs, /opt/homebrew is usually /usr/local instead — check with brew --prefix.

3. Install Jenkins

Use the LTS (Long-Term Support) version — it’s more stable than the weekly releases:

brew install jenkins-lts

4. Start Jenkins as a background service

brew services start jenkins-lts

Check it’s running:

brew services list

5. Unlock and set up Jenkins

Open your browser to:

http://localhost:8080

You’ll hit an “Unlock Jenkins” screen asking for an initial admin password. Get it with:

cat ~/.jenkins/secrets/initialAdminPassword

Paste that in, then:

  • Choose “Install suggested plugins” (fine for most setups)
  • Create your first admin user
  • Confirm the Jenkins URL and finish

Alternative: Docker

If you’d rather keep it containerized (handy if you don’t want Jenkins touching your host Java setup):

docker run -p 8080:8080 -p 50000:50000 -v ~/jenkins_home:/var/jenkins_home jenkins/jenkins:lts

The admin password shows up in the container logs instead of a local file.

Troubleshooting

Jenkins won’t start / can’t reach localhost:8080

Check the service status:

brew services list

Check the logs for errors:

tail -n 50 /opt/homebrew/var/log/jenkins-lts/jenkins-lts.log

Intel Macs: /usr/local/var/log/jenkins-lts/jenkins-lts.log

“An error occurred during installation: No such plugin: X”

This usually means Jenkins’ plugin update-site metadata is stale or didn’t download fully before it tried to install the suggested set. It’s a common hiccup right after a fresh install.

Option 1 — Just click through

Refresh localhost:8080 — it’ll often pick back up at the plugin install screen and succeed on a second attempt.

Option 2 — Restart Jenkins and clear the cached update data

brew services stop jenkins-lts
rm -rf ~/.jenkins/updates
brew services start jenkins-lts

Then reload localhost:8080 in your browser — you may need to go through the unlock step again, or it’ll resume where it left off.

Option 3 — Skip plugin install entirely for now

On the “Customize Jenkins” screen, there’s usually a “Skip and continue as admin” option at the bottom. Create your admin user, get into Jenkins, then install plugins manually afterward via Manage Jenkins → Plugins once the update site has synced properly.