Registry / gcp / boostedblob

boostedblob

JSON →
library1.1.0pypypi✓ verified 25d ago

BoostedBlob is a Python library and command-line tool designed for efficient, async-first file operations across local filesystems, Google Cloud Storage, and Azure Blob Storage. It provides a unified API for common tasks like copying, moving, listing, reading, and writing files. The current version is 1.0.0, which introduced significant API changes, moving from a single generic `Path` object to specific `LocalPath`, `GooglePath`, and `AzurePath` types. Its primary release cadence has been irregular but reached a stable `1.0.0` in April 2024.

pip install boostedblob
INSTALL
IMPORT
SIG · BOOSTEDBLOB
B
boostedblob
gcppythonv1.1.0
Install
5.3s avg
Import
717ms
Disk
61MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v1.1.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
musl
py 3.103.910 runs
installs and imports cleanly · install 0.0s · import 0.606s · 57.4MB
glibc
py 3.103.910 runs
installs and imports cleanly · install 5.3s · import 0.541s · 63MB
61MB installed
● package 61MB
Code
Verified usage

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

LocalPath, AzurePath, GooglePath
from boostedblob.path import LocalPath, AzurePath, GooglePath
from boostedblob import Path
As of v1.0.0, the generic `Path` object was removed in favor of specific path types from `boostedblob.path`.
read_json, write_json
from boostedblob.read import read_json from boostedblob.write import write_json
from boostedblob import read_json, write_json
As of v1.0.0, `read_json` and `write_json` (and other specific operations like `copy`, `move`) were moved into dedicated submodules (`.read`, `.write`, `.copy`, `.move`). Top-level `delete`, `list_dir` are still available.
delete, list_dir
from boostedblob import delete, list_dir

This quickstart demonstrates basic file operations for local paths, and conditional operations for Azure Blob Storage. To run the Azure part, set `AZURE_STORAGE_ACCOUNT_NAME` and `AZURE_STORAGE_CONTAINER` environment variables. For Google Cloud Storage, ensure `boostedblob[gcs]` is installed and set `GOOGLE_APPLICATION_CREDENTIALS` and `GCS_BUCKET_NAME`.

import asyncio import os from boostedblob.path import LocalPath, AzurePath from boostedblob import delete, list_dir from boostedblob.read import read_json from boostedblob.write import write_json async def main(): # 1. Local File Operations print("--- Local File Operations ---") local_path = LocalPath("./boostedblob_quickstart_test.json") try: await write_json({"message": "Hello from BoostedBlob local!"}, local_path) print(f"Wrote to {local_path}") content = await read_json(local_path) print(f"Read from {local_path}: {content}") # Clean up await delete(local_path) print(f"Deleted {local_path}") except Exception as e: print(f"Error during local operations: {e}") # 2. Azure Blob Storage Operations (requires environment variables) print("\n--- Azure Blob Storage Operations ---") azure_account = os.environ.get('AZURE_STORAGE_ACCOUNT_NAME') azure_container = os.environ.get('AZURE_STORAGE_CONTAINER') if azure_account and azure_container: # Example Azure path azure_path = AzurePath(f"az://{azure_account}/{azure_container}/boostedblob_quickstart_azure.json") print(f"Target Azure Path: {azure_path}") try: await write_json({"message": "Hello from BoostedBlob Azure!"}, azure_path) print(f"Wrote to {azure_path}") content = await read_json(azure_path) print(f"Read from {azure_path}: {content}") # Uncomment the line below to delete the file after reading # await delete(azure_path) # print(f"Deleted {azure_path}") print("Azure operations completed. (Deletion is commented out for safety).") except Exception as e: print(f"Azure operations failed (check credentials, account, container, permissions): {e}") else: print("Skipping Azure operations: Set AZURE_STORAGE_ACCOUNT_NAME and AZURE_STORAGE_CONTAINER environment variables to enable.") print("For GCS, install with `boostedblob[gcs]` and set `GOOGLE_APPLICATION_CREDENTIALS` and `GCS_BUCKET_NAME`.") if __name__ == "__main__": asyncio.run(main())
boostedblob --version
Debug
Known issues
breakingThe generic `boostedblob.Path` object was removed in v1.0.0. You must now use specific path types: `LocalPath`, `GooglePath`, or `AzurePath` imported from `boostedblob.path`.
fix
Replace `Path(...)` with `LocalPath(...)`, `GooglePath(...)`, or `AzurePath(...)` and update imports accordingly (e.g., `from boostedblob.path import AzurePath`).
affects: >=1.0.0
breakingSpecific operations like `read_json`, `write_json`, `copy`, and `move` were moved from top-level `boostedblob` imports to dedicated submodules in v1.0.0.
fix
Update imports from `from boostedblob import read_json` to `from boostedblob.read import read_json` (and similarly for `write`, `copy`, `move`). Note that `delete` and `list_dir` remain top-level imports for convenience.
affects: >=1.0.0
breakingThe return type of `list_dir` changed from `AsyncIterator[str]` to `AsyncIterator[boostedblob.path.BasePath]` in v1.0.0.
fix
Adjust code that processes `list_dir` results to expect `BasePath` objects instead of raw strings. Access the path string via `.path` attribute if needed (e.g., `async for item in list_dir(...): print(item.path)`).
affects: >=1.0.0
gotchaAs of v1.0.0, `boostedblob.path.BasePath` objects are immutable. Modifying their attributes directly is no longer possible.
fix
Instead of modifying an existing `BasePath` object, create a new one with the desired changes if you need a different path (e.g., `new_path = old_path.joinpath('new_segment')`).
affects: >=1.0.0
breaking`boostedblob` versions prior to 1.0.0 use type hint syntax (`X | None`) that requires Python 3.10 or newer, leading to a `TypeError` on older Python versions like 3.9.
fix
Use Python 3.10 or newer when working with `boostedblob` versions older than 1.0.0.
affects: <1.0.0
Errors
Common errors & fixes
ImportError: cannot import name 'Path' from 'boostedblob'
The generic `Path` class was removed in boostedblob 1.0.0 and replaced with specific path types like `LocalPath`, `GooglePath`, and `AzurePath`.
fix
Update your imports to use the specific path type relevant to your storage, e.g., `from boostedblob import LocalPath`.
AttributeError: module 'boostedblob' has no attribute 'Path'
In boostedblob 1.0.0, the generic `Path` object was removed from the top-level module, requiring users to import and instantiate specific path types.
fix
Replace `boostedblob.Path(...)` with the appropriate specific path constructor, such as `boostedblob.LocalPath(...)`, `boostedblob.GooglePath(...)`, or `boostedblob.AzurePath(...)`.
ValueError: Path scheme 's3' is not supported. Supported schemes are: 'file', 'gs', 'az'.
A boostedblob path object was instantiated with an unsupported storage scheme (e.g., 's3'), or a malformed path string was provided, as boostedblob only natively supports local files ('file'), Google Cloud Storage ('gs'), and Azure Blob Storage ('az').
fix
Ensure the path string starts with a supported scheme ('file://', 'gs://', 'az://') or that you are using the correct specific path class (e.g., `GooglePath('my-bucket/my-file')` automatically implies 'gs://'). If using a specific path class, ensure the path string is valid for that provider.
Upgrade
Version history
1.1.0latest on PyPI · released Jul 30, 2026
Audit
Dependencies
azure-storage-bloboptionalRequired for Azure Blob Storage functionality (optional extra)
azure-identityoptionalRequired for Azure authentication (optional extra)
google-cloud-storageoptionalRequired for Google Cloud Storage functionality (optional extra)
Agent activity
53 hits · last 30 days
node
46
OpenAI (training)
1
Resources
boostedblob — pip install boostedblob · libregistry