Install & Compatibility
Where this runs
tested against v2.12.0 · 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
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 0.859s · 24.6MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 2.4s · import 0.756s · 25MB
23MB installed
● package 23MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
B2Api
✓ from b2sdk.v3 import B2Api
✗ from b2sdk import B2Api
Since v2.9.1, the B2 SDK officially recommends importing from `b2sdk.v3` for the latest API interface and features. Importing from `b2sdk` directly (which maps to `v2`) is still supported but may not receive new features or might be deprecated in the future.
SqliteAccountInfo
✓ from b2sdk.v3.account_info.sqlite_account_info import SqliteAccountInfo
Used for persisting B2 account authorization information locally.
This quickstart demonstrates how to initialize the `B2Api` client, authorize with your Backblaze B2 credentials (retrieved from environment variables for security), and then list your B2 buckets. This is a common first step for any interaction with B2 Cloud Storage.
import os
from b2sdk.v3 import B2Api
from b2sdk.v3.account_info.sqlite_account_info import SqliteAccountInfo
# It's recommended to store credentials in environment variables
APPLICATION_KEY_ID = os.environ.get('B2_APPLICATION_KEY_ID', 'YOUR_KEY_ID')
APPLICATION_KEY = os.environ.get('B2_APPLICATION_KEY', 'YOUR_KEY')
if APPLICATION_KEY_ID == 'YOUR_KEY_ID' or APPLICATION_KEY == 'YOUR_KEY':
print("Please set B2_APPLICATION_KEY_ID and B2_APPLICATION_KEY environment variables.")
else:
try:
# Initialize account info storage (can be SqliteAccountInfo, InMemoryAccountInfo, etc.)
info = SqliteAccountInfo()
b2_api = B2Api(info)
# Authorize with Backblaze B2
b2_api.authorize_account(
realm='production', # Or 'test' for integration testing
application_key_id=APPLICATION_KEY_ID,
application_key=APPLICATION_KEY
)
print("Successfully authorized with Backblaze B2.")
# Example: List your buckets
print("\nListing buckets:")
buckets = b2_api.list_buckets()
if buckets:
for bucket in buckets:
print(f" - {bucket.name} (ID: {bucket.id_}, Type: {bucket.bucket_type})")
else:
print(" No buckets found.")
except Exception as e:
print(f"An error occurred: {e}")
Debug
Known issues
breakingPython 3.8 support was dropped in `b2sdk` v2.10.0. Projects using `b2sdk` must now run on Python 3.9 or newer.fixUpgrade your Python environment to 3.9 or later.
affects: <2.10.0
gotchaThe recommended API version for `b2sdk` is `v3` since `v2.9.1`. Importing `B2Api` from `b2sdk` directly (i.e., `from b2sdk import B2Api`) will use the older `v2` API, which may lack new features or lead to future compatibility issues.fixUpdate imports to `from b2sdk.v3 import B2Api` for new projects or when updating existing code.
affects: >=2.9.1
gotchaIf using `SqliteAccountInfo` for local credential caching, upgrading to `b2sdk` v2.10.3 from an older version might encounter backwards compatibility issues due to changes in the sqlite schema related to multi-bucket key support.fixIf encountering issues after upgrading, try deleting the local account info file (typically `~/.b2_account_info`) and re-authorizing, or consult the `b2sdk` migration guide if available.
affects: <2.10.3
gotchaA retry bug in `upload_unbound_stream()` for small-file uploads could cause a `ValueError: I/O operation on closed file` if a retryable upload error occurred.fixUpgrade to `b2sdk` v2.10.4 or later to fix this retry behavior.
affects: >=2.9.1, <2.10.4
gotchaThe `b2sdk` library adapted `authorize_account` and key management flows for multi-bucket keys in `v2.9.1`. If you manage application keys that are scoped to multiple buckets, older integrations might need review.fixReview key management logic and ensure it aligns with the multi-bucket key capabilities introduced in `v2.9.1`.
affects: <2.9.1
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'b2sdk.v1'
The user is attempting to import from an outdated or incorrect API version module (`b2sdk.v1`), while the current recommended stable API version is `b2sdk.v2`.
fixUpdate the import statement to `from b2sdk.v2 import ...` instead of `from b2sdk.v1 import ...`.
b2sdk.exception.InvalidAuthToken: Invalid authorization token. Server said: (bad_auth_token)
The provided `applicationKeyId` or `applicationKey` for account authorization is incorrect, expired, or does not possess the necessary capabilities for the attempted operation.
fixVerify that the `applicationKeyId` and `applicationKey` are correct and have the appropriate permissions configured in the Backblaze B2 console. Regenerate the key if uncertain or if it has expired.
ValueError: I/O operation on closed file
This error, particularly in the context of `upload_unbound_stream()`, occurred in older `b2sdk` versions where a retryable upload error could cause a one-shot buffered stream to be reopened after it was already closed.
fixUpgrade the `b2sdk` library to version 2.10.4 or newer, as this specific bug was addressed in recent releases.
b2sdk.exception.ChecksumMismatch: sha1 checksum mismatch -- bad data
The SHA1 checksum of a downloaded file does not match the checksum recorded by Backblaze B2, indicating potential data corruption during transfer or a data integrity issue on the server.
fixWhile `b2sdk` reports the mismatch, the root cause is often external. Retry the download, potentially from a different network or after some time, as it might be a transient network issue. If persistent, investigate network stability or contact Backblaze support.
B2ConnectionError. Max retries exceeded. Caused by NewConnectionError. Failed to establish a new connection
The `b2sdk` library failed to establish a network connection to the Backblaze B2 API endpoints after multiple retries, typically due to local network issues, firewall restrictions, or incorrect API endpoint configurations.
fixCheck your internet connectivity, firewall settings, and ensure that the Backblaze B2 API endpoints (e.g., `api.backblazeb2.com`) are not blocked and are reachable from your environment. If a custom API URL is used, verify its correctness.
Upgrade
Version history
2.12.0latest on PyPI · released May 5, 2026
Audit
Dependencies
No dependency data recorded yet.