Jira API (Python)

3.10.5 (jira) / 4.0.7 (atlassian-python-api) · active · verified Tue Mar 17

Two separate community-maintained Python libraries exist for Jira: 'jira' (pip install jira, v3.10.5) and 'atlassian-python-api' (pip install atlassian-python-api, v4.0.7). Neither is an official Atlassian SDK. They have different APIs, auth patterns, and JQL methods. Agents frequently mix them up.

Warnings

breaking Two competing packages: 'jira' (imports as JIRA) and 'atlassian-python-api' (imports as Jira). Tutorials and LLM-generated code mix them constantly. They are not interchangeable.
Fix: Pick one. 'jira' is better for pure Jira work. 'atlassian-python-api' covers Confluence/Bitbucket/ServiceDesk too.
breaking Jira Cloud blocks password auth. API token must be passed as the password field, not an actual password. Regular account passwords return 401.
Fix: Generate token at id.atlassian.com/manage-profile/security/api-tokens. Pass as password= (jira pkg) or password= (atlassian pkg).
breaking atlassian-python-api: cloud=True is required for Jira Cloud. Omitting it causes requests to fail against Cloud endpoints silently or with confusing 404s.
Fix: Always pass cloud=True when connecting to *.atlassian.net
breaking atlassian-python-api: jql() method is deprecated for Jira Cloud. Use enhanced_jql() instead.
Fix: Replace jira.jql(...) with jira.enhanced_jql(...) for Cloud instances.
gotcha Jira Server/Data Center uses Personal Access Token (PAT) via token= parameter. Jira Cloud uses API token via username+password. The auth pattern differs by deployment type.
Fix: Server/DC: Jira(url=..., token=pat_token). Cloud: Jira(url=..., username=email, password=api_token, cloud=True)
gotcha jira package: search_issues() returns max 50 results by default. Silent truncation — no error raised if results exceed limit.
Fix: Pass maxResults=False or paginate with startAt parameter to retrieve all results.
gotcha Neither package is an official Atlassian product. Atlassian has no official Python SDK. Both are community-maintained.
Fix: For production use, pin versions. Both packages have had breaking changes between minor versions.

Install

pip install jira Python (jira package — pycontribs)
pip install atlassian-python-api Python (atlassian-python-api — atlassian-api)

Imports

JIRA
```
from jira import JIRA
```
jira package uses JIRA (uppercase). atlassian-python-api uses Jira (mixed case). Mixing them causes ImportError or silent wrong-class usage.
Jira
```
from atlassian import Jira
```
atlassian-python-api exports Jira (mixed case). jira package exports JIRA (uppercase). The casing difference is the only signal which package you're using.

Quickstart

Both packages side-by-side. Pick one and stay consistent.

# --- Option A: jira package (pycontribs) ---
from jira import JIRA

jira = JIRA(
    server='https://your-domain.atlassian.net',
    basic_auth=('your-email@example.com', 'your-api-token')
)
issue = jira.issue('PROJ-1')
print(issue.fields.summary)

# --- Option B: atlassian-python-api ---
from atlassian import Jira

jira = Jira(
    url='https://your-domain.atlassian.net',
    username='your-email@example.com',
    password='your-api-token',
    cloud=True  # required for Cloud
)
data = jira.enhanced_jql('project = PROJ ORDER BY created DESC')
print(data)

view raw JSON →