jira

library3.10.5 (jira) / 4.0.7 (atlassian-python-api)pypypi✓ verified 53d ago

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.

http-networking crm-productivity communication web-framework

pip install jira

github ↗package ↗docs ↗

Install & Compatibility

Where this runs

tested against v3.10.5 · 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

glibc

py 3.10

8/10 runs

py 3.11

8/10 runs

py 3.12

8/10 runs

py 3.13

8/10 runs

py 3.9

8/10 runs

Code

Verified usage

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

JIRA

✓ from jira import JIRA

✗ from atlassian 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

✗ from jira 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.

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)

Debug

Known issues

breakingTwo 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.

affects: all

breakingJira Cloud blocks password auth. API token must be passed as the password field, not an actual password. Regular account passwords return 401 or 404 (often with 'Issue does not exist or you do not have permission to see it' and 'X-Seraph-Loginreason: AUTHENTICATED_FAILED' headers).

fix

Generate token at id.atlassian.com/manage-profile/security/api-tokens. Pass as password= (jira pkg) or password= (atlassian pkg).

affects: all

breakingatlassian-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

affects: all

breakingatlassian-python-api: jql() method is deprecated for Jira Cloud. Use enhanced_jql() instead.

fix

Replace jira.jql(...) with jira.enhanced_jql(...) for Cloud instances.

affects: all

gotchaJira 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)

affects: all

gotchajira 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.

affects: all

gotchaNeither 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.

affects: all

Errors

Common errors & fixes

jira.exceptions.JIRAError: JiraError HTTP 401 url: <JIRA_URL> text: Client must be authenticated to access this resource.

This error typically occurs when the authentication credentials provided are incorrect, such as using a password instead of an API token, an incorrect email/username, or an expired/revoked API token, or due to insufficient permissions.

fix

For Jira Cloud, use your Atlassian email address as the username and a generated API token as the password. Ensure the API token has the necessary permissions. Example for 'jira' library: `jira = JIRA(server='https://your-domain.atlassian.net', basic_auth=('your_email@example.com', 'YOUR_API_TOKEN'))`. Example for 'atlassian-python-api' library: `jira = Atlassian(url='https://your-domain.atlassian.net', username='your_email@example.com', password='YOUR_API_TOKEN')`

ModuleNotFoundError: No module named 'jira'

The Python interpreter cannot find the 'jira' module because it is either not installed in the active environment or the environment path is incorrectly configured.

fix

Install the required library using pip. If using the 'jira' library: `pip install jira`. If using 'atlassian-python-api': `pip install atlassian-python-api`. Ensure you install it in the correct virtual environment if one is being used.

AttributeError: '<class 'jira.resources.Issue'> object has no attribute 'fields'

This error often indicates that you are attempting to access an attribute (like `fields`) on an object that is not a valid `jira.resources.Issue` instance, or an attribute that is lazily loaded and not retrieved by default. A related common error is `AttributeError: 'NoneType' object has no attribute 'name'` when an optional field (like assignee) is not present on an issue.

fix

Verify that the object you are calling `.fields` on is indeed a `jira.resources.Issue` instance. For attributes that might be `None`, add explicit checks: `if issue.fields.assignee: print(issue.fields.assignee.displayName)`. For fields that require explicit loading (like 'worklog'), use the `expand` parameter when fetching the issue: `issue = jira.issue('ISSUE-KEY', expand='changelog,worklog')`.

jira.exceptions.JIRAError: JiraError HTTP 400 url: <JIRA_URL> text: <Specific Jira API error message>

This 'Bad Request' error means the data sent to the Jira API is malformed, incomplete, or violates Jira's validation rules for the specific operation (e.g., missing a required field, invalid field format, or an issue type that does not exist in the project).

fix

Examine the `text` portion of the error message for specific details on what is incorrect. Adjust your payload to include all mandatory fields with correct data types and formats as per your Jira instance's configuration (e.g., provide values for all required custom fields for the issue type being created).

jira.exceptions.JIRAError: JiraError HTTP 410 url: <JIRA_URL>/rest/api/2/search text: The requested API has been removed. Please migrate to the /rest/api/3/search/jql API.

This error occurs because Jira Cloud has deprecated and removed its API v2 search endpoint. Your current code or an older version of the `jira` Python library is still attempting to use this retired endpoint.

fix

Upgrade the 'jira' Python library to the latest version using `pip install --upgrade jira`. If the problem persists after upgrading, review your code to ensure it's not explicitly targeting API v2 endpoints and is compatible with the API v3 changes, particularly for search queries.

Upgrade

Version history

3.10.5latest on PyPI

Audit

Dependencies

No dependency data recorded yet.

Agent activity

91 hits · last 30 days

node

seranking-bot

ahrefsbot

mj12bot

amazonbot

bytedance

Resources

githubhttps://github.com/pycontribs/jira ↗

packagehttps://pypi.org/project/jira/ ↗

docshttps://jira.readthedocs.io ↗