Registry / crm-productivity / atlassian-python-api

atlassian-python-api

JSON →
library5.0.3pypypi✓ verified 24d ago

The `atlassian-python-api` library provides a comprehensive and convenient Python wrapper for interacting with various Atlassian products, including Jira, Confluence, Bitbucket, Crowd, Service Desk, Xray, and Bamboo. It supports both Atlassian Cloud and Server/Data Center instances by leveraging their official REST APIs, along with some additional private methods and protocols. Currently at version 4.0.7, the library maintains an active development and release cadence, frequently adding new features, bug fixes, and adjustments for evolving Atlassian APIs.

pip install atlassian-python-api
INSTALL
IMPORT
SIG · ATLASSIAN-PYTHON-A
A
atlassian-python-api
crm-productivitypythonv5.0.3
Install
Import
Disk
Pass rate
0/ 10
Env Coverage0 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v5.0.3 · 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
1/2 runs
1/2 runs
py 3.11
1/2 runs
1/2 runs
py 3.12
1/2 runs
1/2 runs
py 3.13
1/2 runs
1/2 runs
py 3.9
1/2 runs
1/2 runs
Code
Verified usage

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

Jira
from atlassian import Jira
Confluence
from atlassian import Confluence
Bitbucket
from atlassian import Bitbucket
Jira
from atlassian.jira import JiraCloud
from atlassian.jira import Jira
For Jira Cloud, prefer `JiraCloud` for specific cloud features, though `Jira` often works for basic operations with cloud=True parameter.

This quickstart demonstrates how to connect to Jira Cloud using an API token, which is the recommended authentication method for cloud instances. It then retrieves the current user's display name and lists the first five available projects to verify the connection and basic functionality. Environment variables are used for sensitive credentials.

import os from atlassian import Jira # For Jira Cloud, use API Token authentication. # Generate an API token at: https://id.atlassian.com/manage-profile/security/api-tokens JIRA_URL = os.environ.get('ATLASSIAN_JIRA_URL', 'https://your-domain.atlassian.net') JIRA_EMAIL = os.environ.get('ATLASSIAN_JIRA_EMAIL', 'your_email@example.com') JIRA_API_TOKEN = os.environ.get('ATLASSIAN_JIRA_API_TOKEN', 'YOUR_API_TOKEN') if not all([JIRA_URL, JIRA_EMAIL, JIRA_API_TOKEN]): print("Please set ATLASSIAN_JIRA_URL, ATLASSIAN_JIRA_EMAIL, and ATLASSIAN_JIRA_API_TOKEN environment variables.") else: try: jira = Jira( url=JIRA_URL, username=JIRA_EMAIL, password=JIRA_API_TOKEN, # API token for Cloud cloud=True # Important for Jira Cloud ) # Test connection by getting current user current_user = jira.myself() print(f"Successfully connected to Jira. Current user: {current_user['displayName']}") # Example: Get all projects projects = jira.get_all_projects(start=0, limit=5) print(f"First 5 projects: {[p['name'] for p in projects]}") except Exception as e: print(f"Error connecting to Jira or fetching data: {e}")
Debug
Known issues
breakingVersion 4.0.0 removed Python 2 support. Projects using `atlassian-python-api` with Python 2 will break upon upgrade.
fix
Migrate your project to Python 3.9 or newer. Python 3.9+ is required for version 4.0.0 and above.
affects: >=4.0.0
breakingAtlassian Cloud APIs no longer support basic authentication with a username and password (deprecated since June 2019). Attempting to use a password for Cloud authentication will result in an 'invalid credentials' error.
fix
For Atlassian Cloud, use API tokens for basic authentication (username is email, password is API token) or OAuth 2.0. Generate API tokens from your Atlassian account security settings.
affects: All versions interacting with Atlassian Cloud APIs after June 2019
gotchaThere are significant API and authentication differences between Atlassian Cloud and Server/Data Center instances. This includes authentication methods (API Token for Cloud vs. username/password/PAT for Server) and content ID formats (UUID strings for Cloud vs. numeric IDs for Server).
fix
Always consult the `atlassian-python-api` documentation for the specific product (Jira, Confluence, Bitbucket, etc.) and deployment type (Cloud or Server/DC) you are targeting to ensure correct API calls and authentication parameters. Some modules, like Confluence, have dedicated `ConfluenceCloud` and `ConfluenceServer` classes.
affects: All versions
gotchaThe `attach_file()` method in Confluence may not create a new revision when re-uploading a file with the same name, potentially leading to errors. Additionally, `download_attachments_from_page` in version 4.0.0 started returning bytes instead of text, which might require changes in how file content is handled.
fix
For `attach_file()`, ensure unique filenames or implement logic to handle existing attachments if new revisions are expected. For `download_attachments_from_page`, explicitly decode the returned bytes to text if needed (e.g., `.decode('utf-8')`).
affects: >=4.0.0 for `download_attachments_from_page`; various for `attach_file()`
deprecatedAtlassian itself is deprecating some Jira JQL search API endpoints (effective May 1, 2025). While `atlassian-python-api` has updated to support the new `search/jql` endpoint, older scripts or direct API calls might be affected.
fix
Ensure you are using the latest `atlassian-python-api` version (4.0.0 or later added `search/jql` support) and review your JQL search implementations to align with Atlassian's updated API guidelines.
affects: Scripts using older Jira JQL search APIs, potentially versions of `atlassian-python-api` prior to those implementing the new `search/jql` endpoint (e.g., pre-4.0.0).
gotchaInstallation may fail with a 'subprocess-exited-with-error' and 'krb5-config: not found' if a transitive dependency attempts to build components requiring Kerberos development headers. This often occurs in minimal environments like `python:*-slim` Docker images.
fix
Ensure Kerberos development headers are available in your build environment. For Debian/Ubuntu-based systems, install `libkrb5-dev` (e.g., `apt-get update && apt-get install -y libkrb5-dev`). For RHEL/CentOS-based systems, install `krb5-devel`.
affects: All versions
gotchaWhen attempting to install `gssapi` (often a dependency for Kerberos authentication with Atlassian Server/Data Center instances), the build process may fail on minimal Linux distributions (like Alpine Linux) due to missing Kerberos development libraries.
fix
Before installing `gssapi` or `atlassian-python-api` with Kerberos authentication features, ensure that Kerberos development libraries are installed on your system. For Alpine Linux, this typically means running `apk add krb5-dev`. For Debian/Ubuntu, it would be `apt-get install libkrb5-dev`.
affects: All versions when using Kerberos authentication, or when `gssapi` is an implicit dependency in the environment.
Errors
Common errors & fixes
requests.exceptions.HTTPError: 401 Client Error
This error occurs when authentication credentials are incorrect or missing.
fix
Ensure that the correct username and password or API token are provided when initializing the Confluence object.
SyntaxError: invalid syntax
This error occurs when using Python 2.x, as the atlassian-python-api library requires Python 3.x.
fix
Upgrade to Python 3.x to use the atlassian-python-api library.
ImportError: cannot import name 'bitbucket' from 'atlassian'
This error occurs when the atlassian-python-api library is not installed or not properly installed.
fix
Install the atlassian-python-api library using pip: pip install atlassian-python-api.
AttributeError: module 'atlassian' has no attribute 'Jira'
This error occurs when the atlassian-python-api library is not installed or not properly installed.
fix
Install the atlassian-python-api library using pip: pip install atlassian-python-api.
ModuleNotFoundError: No module named 'atlassian'
This error occurs when the atlassian-python-api library is not installed.
fix
Install the atlassian-python-api library using pip: pip install atlassian-python-api.
Upgrade
Version history
5.0.3latest on PyPI · released Aug 17, 2026
Audit
Dependencies
beautifulsoup4requiredHTML parsing for certain operations
deprecatedrequiredDecorator for marking deprecated functions
jmespathrequiredJSON query language for Python
oauthlibrequiredOAuth 1.0/2.0 implementation
requestsrequiredHTTP library
requests_oauthlibrequiredOAuth support for Requests
typing-extensionsrequiredBackports of new typing features
requests-kerberosoptionalKerberos authentication support
Agent activity
64 hits · last 30 days
node
52
OpenAI (training)
1
Resources
atlassian-python-api — pip install atlassian-python-api · libregistry