{"id":4365,"library":"jenkinsapi","title":"JenkinsAPI","description":"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.","status":"active","version":"0.3.22","language":"python","source_language":"en","source_url":"https://github.com/pycontribs/jenkinsapi","tags":["jenkins","ci","cd","automation","api","continuous-integration"],"install":[{"cmd":"pip install jenkinsapi","lang":"bash","label":"Install stable version"}],"dependencies":[],"imports":[{"note":"This is the primary class for connecting to a Jenkins server.","symbol":"Jenkins","correct":"from jenkinsapi.jenkins import Jenkins"}],"quickstart":{"code":"import os\nfrom jenkinsapi.jenkins import Jenkins\n\nJENKINS_URL = os.environ.get('JENKINS_URL', 'http://localhost:8080')\nJENKINS_USERNAME = os.environ.get('JENKINS_USERNAME', 'admin') # Or 'JENKINS_USER'\nJENKINS_API_TOKEN = os.environ.get('JENKINS_API_TOKEN', 'your_api_token_here') # Use an API token, not a user's password\n\ndef connect_to_jenkins():\n    try:\n        # It's highly recommended to use an API token for authentication,\n        # which can be generated from your Jenkins user configuration page.\n        server = Jenkins(JENKINS_URL, username=JENKINS_USERNAME, password=JENKINS_API_TOKEN)\n        print(f\"Successfully connected to Jenkins at {JENKINS_URL}. Jenkins version: {server.version}\")\n        \n        # Example: Get the number of jobs\n        print(f\"Number of jobs configured: {len(server.jobs)}\")\n\n        # Example: List names of first 5 jobs\n        # print(\"First 5 job names:\")\n        # for i, job_name in enumerate(server.jobs.keys()):\n        #     if i >= 5:\n        #         break\n        #     print(f\"  - {job_name}\")\n\n    except Exception as e:\n        print(f\"Failed to connect to Jenkins or retrieve information: {e}\")\n        print(\"Ensure JENKINS_URL, JENKINS_USERNAME, and JENKINS_API_TOKEN environment variables are set correctly.\")\n\nif __name__ == '__main__':\n    connect_to_jenkins()","lang":"python","description":"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."},"warnings":[{"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.","message":"Jenkins 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.","severity":"breaking","affected_versions":"Jenkins >= 1.518"},{"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.","message":"The 'Jenkins Location' in Jenkins' global settings must be correctly configured, otherwise the REST API (which `jenkinsapi` uses) may not work as expected.","severity":"gotcha","affected_versions":"All Jenkins versions"},{"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.","message":"For 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.","severity":"gotcha","affected_versions":"Jenkins >= 1.426"},{"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.","message":"When 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.","severity":"gotcha","affected_versions":"All versions, especially with large Jenkins instances"},{"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.","message":"Reliably 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.","severity":"gotcha","affected_versions":"All versions, especially under high load"}],"env_vars":null,"search_vec":"'0.3.22':67 'activ':51 'address':56 'api':27,72 'artifact':42 'autom':44,71 'bug':57 'build':39 'cd':70 'ci':69 'continu':19,74 'continuous-integr':73 'current':64 'easier':30 'featur':61 'fix':58 'integr':20,75 'interact':15 'interfac':13 'jenkin':18,25,46,68 'jenkinsapi':1,2 'job':38 'librari':6,49 'maintain':52 'make':28 'manag':37 'new':60 'node':40 'object':11 'object-ori':10 'orient':12 'provid':8 'python':5 'queri':32 'regular':54 'rest':26 'server':21,34 'state':36 'task':47 'updat':55 'various':45 'version':66 'wrap':23","created_at":"2026-04-12T08:52:39.787776+00:00","updated_at":"2026-04-16T15:51:55.627904+00:00","problems":[{"fix":"Install the library using pip: `pip install jenkinsapi`","cause":"The jenkinsapi library is not installed in the Python environment being used, or the environment is not correctly activated.","error":"ModuleNotFoundError: No module named 'jenkinsapi'"},{"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`.","cause":"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`).","error":"AttributeError: 'module' object has no attribute 'Jenkins'"},{"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`).","cause":"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.","error":"Invalid password/token for user:"},{"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.","cause":"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'.","error":"jenkinsapi.custom_exceptions.JenkinsAPIException"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"0.3.23","cli_name":"","cli_version":null,"type":"library","homepage":null,"github":null,"docs":null,"changelog":null,"pypi":"https://pypi.org/project/jenkinsapi/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["devops","http-networking"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-08-29","next_check":"2026-07-28","install_tag":null}}