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
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.fixMigrate 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.fixFor 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).fixAlways 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.fixFor `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.fixEnsure 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.fixEnsure 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.fixBefore 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.
fixEnsure 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.
fixUpgrade 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.
fixInstall 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.
fixInstall 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.
fixInstall 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