Atlassian Python API Wrapper

4.0.7 · active · verified Sat Apr 11

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.

Common errors

```
requests.exceptions.HTTPError: 401 Client Error
```
cause 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
```
cause 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'
```
cause 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'
```
cause 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'
```
cause 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.

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.
gotcha Installation 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`.
gotcha When 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`.

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
wrong:
```
from atlassian.jira import Jira
```
correct:
```
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 →