Atlassian Python API Wrapper

4.0.7 · active · verified Wed Apr 08

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.

Warnings

breaking Version 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.
breaking Atlassian 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.
gotcha There 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.
gotcha The `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')`).
deprecated Atlassian 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.

Install

pip install atlassian-python-api Install stable version
pip install atlassian-python-api[kerberos] Install with Kerberos authentication support

Imports

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

Quickstart

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}")

view raw JSON →