Registry / devops / jenkinsapi

jenkinsapi

JSON →
library0.3.23pypypi✓ verified 22d ago

JenkinsAPI is a Python library that provides an object-oriented interface for interacting with a Jenkins continuous integration server. It wraps the Jenkins REST API, making it easier to query the server's state, manage jobs, builds, nodes, and artifacts, and automate various Jenkins tasks. The library is actively maintained, with regular updates addressing bug fixes and new features, and is currently at version 0.3.22.

pip install jenkinsapi
INSTALL
IMPORT
SIG · JENKINSAPI
J
jenkinsapi
devopspythonv0.3.23
Install
2.6s avg
Import
485ms
Disk
24MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v0.3.23 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.95 runs
installs and imports cleanly · install 0.0s · import 0.496s · 25.6MB
glibc
py 3.103.95 runs
installs and imports cleanly · install 2.6s · import 0.474s · 26MB
24MB installed
● package 24MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

Jenkins
from jenkinsapi.jenkins import Jenkins
This is the primary class for connecting to a Jenkins server.

This quickstart demonstrates how to connect to a Jenkins server using the `Jenkins` class and retrieve basic information like the server version and the count of configured jobs. It uses environment variables for Jenkins URL, username, and API token for secure credential management.

import os from jenkinsapi.jenkins import Jenkins JENKINS_URL = os.environ.get('JENKINS_URL', 'http://localhost:8080') JENKINS_USERNAME = os.environ.get('JENKINS_USERNAME', 'admin') # Or 'JENKINS_USER' JENKINS_API_TOKEN = os.environ.get('JENKINS_API_TOKEN', 'your_api_token_here') # Use an API token, not a user's password def connect_to_jenkins(): try: # It's highly recommended to use an API token for authentication, # which can be generated from your Jenkins user configuration page. server = Jenkins(JENKINS_URL, username=JENKINS_USERNAME, password=JENKINS_API_TOKEN) print(f"Successfully connected to Jenkins at {JENKINS_URL}. Jenkins version: {server.version}") # Example: Get the number of jobs print(f"Number of jobs configured: {len(server.jobs)}") # Example: List names of first 5 jobs # print("First 5 job names:") # for i, job_name in enumerate(server.jobs.keys()): # if i >= 5: # break # print(f" - {job_name}") except Exception as e: print(f"Failed to connect to Jenkins or retrieve information: {e}") print("Ensure JENKINS_URL, JENKINS_USERNAME, and JENKINS_API_TOKEN environment variables are set correctly.") if __name__ == '__main__': connect_to_jenkins()
Debug
Known issues
breakingJenkins versions 1.518 and above require disabling 'Prevent Cross Site Request Forgery exploits' in Jenkins' global security configuration for `jenkinsapi` to function correctly without additional configuration for CSRF tokens.
fix
Navigate to 'Manage Jenkins' > 'Configure Global Security' and uncheck 'Prevent Cross Site Request Forgery exploits'. For more secure setups, consider proxying requests or implementing a custom CSRF handling mechanism.
affects: Jenkins >= 1.518
gotchaThe 'Jenkins Location' in Jenkins' global settings must be correctly configured, otherwise the REST API (which `jenkinsapi` uses) may not work as expected.
fix
In Jenkins, go to 'Manage Jenkins' > 'Configure System' and ensure 'Jenkins Location' (Jenkins URL) is set to the correct publicly accessible URL of your Jenkins instance.
affects: All Jenkins versions
gotchaFor Jenkins versions 1.426 and above, it is strongly recommended to use a Jenkins API token for authentication instead of a user's literal password. Using passwords directly is less secure.
fix
Generate an API token for your user in Jenkins (User > Configure > API Token) and use this token as the `password` argument when initializing the `Jenkins` object.
affects: Jenkins >= 1.426
gotchaWhen connecting to a Jenkins instance with a very large number of jobs, `jenkinsapi` might attempt to eagerly load information for all jobs, which can lead to long delays or timeouts. This behavior may cause scripts to hang or run out of memory.
fix
While `jenkinsapi` itself doesn't offer a 'lazy' loading option at the top level for all objects, be mindful of operations that iterate over `server.jobs` or similar collections. Consider fetching specific jobs or using filters if available, or exploring alternative Jenkins Python clients (like `python-jenkins` or `api4jenkins`) if this becomes a persistent performance bottleneck.
affects: All versions, especially with large Jenkins instances
gotchaReliably tracking build queue items and their execution status can be challenging on highly active Jenkins servers. Queue items might be deleted between API calls, potentially leading to incorrect build status mappings or missed build events.
fix
Implement robust retry mechanisms and careful state tracking when interacting with the build queue. Be aware of potential race conditions and consider using Jenkins' built-in mechanisms for build notifications or webhooks if available and suitable for your use case, or poll build status with appropriate delays and error handling.
affects: All versions, especially under high load
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'jenkinsapi'
The jenkinsapi library is not installed in the Python environment being used, or the environment is not correctly activated.
fix
Install the library using pip: `pip install jenkinsapi`
AttributeError: 'module' object has no attribute 'Jenkins'
This error often occurs when a Python script intended to use `jenkinsapi` is incorrectly named `jenkins.py` or `jenkinsapi.py`, leading to a name collision where Python tries to import the local script instead of the installed library. It can also happen when attempting to import `Jenkins` directly from a module that doesn't expose it that way (e.g., `import jenkins` instead of `from jenkinsapi.jenkins import Jenkins`).
fix
Rename your Python script if it's named `jenkins.py` or `jenkinsapi.py` to something unique (e.g., `my_jenkins_script.py`). Ensure you are importing the `Jenkins` class correctly: `from jenkinsapi.jenkins import Jenkins`.
Invalid password/token for user:
Authentication to the Jenkins server failed, usually due to incorrect username, an invalid password, or providing a password instead of an API token when the Jenkins security configuration expects an API token for programmatic access.
fix
Verify the username and ensure you are using a Jenkins API token as the password for programmatic access. The API token can be found/generated in your Jenkins user's 'Configure' page (e.g., `http://your-jenkins-server/user/<username>/configure`).
jenkinsapi.custom_exceptions.JenkinsAPIException
This is a general exception from `jenkinsapi` indicating an issue during interaction with the Jenkins server, often related to job operations (e.g., creating, reconfiguring, or querying jobs), permissions, or CSRF protection. Common specific messages include 'No such job' or 'Failed to persist config.xml'.
fix
Check the detailed error message accompanying the exception for specific clues. Common solutions include: ensuring the job exists and its name is correct, verifying the user has sufficient permissions for the requested operation, and, if applicable, correctly handling Jenkins's CSRF protection by using `jenkinsapi.utils.crumb_requester.CrumbRequester` when initializing the Jenkins object.
Upgrade
Version history
0.3.23latest on PyPI · released Apr 21, 2026
Audit
Dependencies

No dependency data recorded yet.

Agent activity
9 hits · last 30 days
node
8
Resources