Python Jenkins API Client

1.8.3 · active · verified Thu Apr 09

Python-jenkins is a Python client library for the Jenkins Remote API, allowing programmatic interaction with Jenkins CI/CD servers. It provides methods to manage jobs, builds, nodes, plugins, and users. The current version is 1.8.3, and it receives maintenance releases roughly annually.

Warnings

deprecated Prefer Jenkins API tokens over user passwords for authentication.
Fix: Generate an API token for your Jenkins user (User -> Configure -> Add new Token) and use it as the `password` argument in `jenkins.Jenkins()`. This enhances security.
gotcha SSL certificate verification can fail with self-signed or corporate certificates.
Fix: If you encounter SSL errors, you can disable SSL verification (use with caution in production) by passing `ssl_verify=False` to the `jenkins.Jenkins()` constructor. Alternatively, configure your system or the `requests` library to trust your certificate authority.
gotcha Connection and API errors are raised as `jenkins.JenkinsException`.
Fix: Always wrap your Jenkins API calls in `try...except jenkins.JenkinsException:` blocks to gracefully handle network issues, authentication failures, and API-specific errors reported by the Jenkins server.

Install

pip install python-jenkins Install stable version

Imports

Jenkins
```
from jenkins import Jenkins
```
JenkinsException
```
from jenkins import JenkinsException
```
For proper error handling and connection issues.

Quickstart

This quickstart demonstrates how to connect to a Jenkins instance using environment variables for credentials (preferring API tokens), retrieve the current user and Jenkins version, and list existing jobs. It includes basic error handling for connection and API issues.

import jenkins
import os

# Configure Jenkins connection details using environment variables for security
JENKINS_URL = os.environ.get('JENKINS_URL', 'http://localhost:8080')
JENKINS_USER = os.environ.get('JENKINS_USER', 'admin')
JENKINS_API_TOKEN = os.environ.get('JENKINS_API_TOKEN', 'your_jenkins_api_token') # Prefer API token over password

try:
    # Initialize the Jenkins client
    server = jenkins.Jenkins(JENKINS_URL, username=JENKINS_USER, password=JENKINS_API_TOKEN)

    # Get basic information
    user_info = server.get_whoami()
    jenkins_version = server.get_version()
    print(f'Connected to Jenkins {jenkins_version} as {user_info["fullName"]}')

    # List jobs
    jobs = server.get_jobs()
    print(f'Found {len(jobs)} jobs. First 5 job names:')
    for job in jobs[:5]:
        print(f'- {job["name"]}')

except jenkins.JenkinsException as e:
    print(f"Error connecting to or interacting with Jenkins: {e}")
except Exception as e:
    print(f"An unexpected error occurred: {e}")

view raw JSON →