Jenkins Installation Guide - Mac and Amazon Linux

Installing Jenkins

Jenkins requires a JDK to run. Jenkins LTS currently requires Java 17 or newer, and weekly releases require Java 21 or newer. As of 2026, installing Java 21 is the safest bet.

Note that the JVM version running Jenkins and the JDK version used for builds are separate concerns. You can run Jenkins itself on Java 17/21 while building your projects with JDK 8 or 11 configured in Global Tool Configuration.

If Jenkins Was Previously Installed

If Jenkins was already installed on the machine, simply reinstalling it may cause JENKINS_HOME to be set to an unexpected path because the ~/.jenkins directory already exists.

To avoid this, completely remove the .jenkins directory and uninstall Jenkins before reinstalling with the commands below.

Mac

On Mac, install Jenkins via Homebrew.

brew install jenkins-lts
brew services start jenkins-lts

After installation, navigate to http://localhost:8080 to access the initial setup screen.

Retrieve the initial admin password with:

cat ~/.jenkins/secrets/initialAdminPassword

To completely uninstall Jenkins on Mac, run the following in order:

brew services stop jenkins-lts
brew uninstall jenkins-lts
rm -rf ~/.jenkins

Amazon Linux

Refer to the official guide for the full walkthrough.

Here's the installation process for Amazon Linux 2023:

# Update system
sudo yum update -y

# Add Jenkins repository
sudo wget -O /etc/yum.repos.d/jenkins.repo https://pkg.jenkins.io/redhat-stable/jenkins.repo
sudo rpm --import https://pkg.jenkins.io/redhat-stable/jenkins.io-2023.key

# Install Java (Amazon Corretto 17 or 21)
sudo dnf install java-17-amazon-corretto -y

# Install Jenkins
sudo yum install jenkins -y

# Start Jenkins
sudo systemctl enable jenkins
sudo systemctl start jenkins

After installation, access Jenkins at http://<instance-IP>:8080. Make sure port 8080 is open in your EC2 security group.

Retrieve the initial admin password with:

sudo cat /var/lib/jenkins/secrets/initialAdminPassword

You may also want to set up a Node.js environment after installing Jenkins.

# Install nvm and node
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash
. ~/.nvm/nvm.sh
nvm install --lts
nvm use --lts
nvm alias default lts/*

# Install pm2 and yarn
npm i -g pm2 yarn

Migrating the .jenkins Directory

When reinstalling Jenkins, some contents of the existing .jenkins directory can be migrated over.

From experimentation, the following directories worked correctly after being copied as-is:

users — existing user account data
nodes — registered node (agent) configurations

Copy these folders into the ~/.jenkins path of the newly installed Jenkins. After copying, go to Manage Jenkins → Reload Configuration from Disk in the web UI to apply changes without restarting.

Managing the Jenkins Directory

Jenkins stores all configuration and build data under the ~/.jenkins directory. The key structure looks like this:

~/.jenkins/
├── config.xml          # Global Jenkins configuration
├── jobs/               # Build job configs and history
│   └── [JOB_NAME]/
│       ├── config.xml
│       ├── builds/
│       └── workspace/  # Source code checkout location
├── nodes/              # Node (agent) configurations
├── plugins/            # Installed plugins
├── users/              # User data
├── secrets/            # Credentials and secrets
└── workspace/          # Workspaces

Over time, the builds/ and workspace/ directories under jobs/ can grow significantly. Keep an eye on disk usage to avoid running out of space.