blobfile

library3.3.0pypypi✓ verified 25d ago

blobfile is a Python library that provides a unified interface for reading and writing files across local and remote blob storage systems, including Google Cloud Storage (GCS) and Azure Blob Storage (ABS). It offers an API similar to Python's built-in `open()` function, along with equivalents of common `os.path` and `shutil` operations. The current version is 3.2.0, released in April 2026, with a release cadence of approximately one major version per year.

data database gcp azure http-networking

pip install blobfile

github ↗package ↗

INSTALL

IMPORT

SIG · BLOBFILE

blobfile

datapythonv3.3.0

Install

2.8s avg

Import

490ms

Disk

39MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v3.3.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.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.522s · 40.5MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 2.8s · import 0.458s · 42MB

39MB installed

● package 39MB

Code

Verified usage

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

BlobFile

✓ from blobfile import BlobFile

✗ from blobfile import blobfile

The correct import is case-sensitive; 'BlobFile' is the class name.

exists

✓ from blobfile import exists

✗ from blobfile import exist

The function name is 'exists', not 'exist'.

This example demonstrates writing to, checking the existence of, and reading from a file in Google Cloud Storage using blobfile.

import blobfile as bf # Write a file to Google Cloud Storage with bf.BlobFile('gs://my-bucket-name/cats', 'wb') as f: f.write(b'meow!') # Check if the file exists print('exists:', bf.exists('gs://my-bucket-name/cats')) # Read the file back with bf.BlobFile('gs://my-bucket-name/cats', 'rb') as f: print('contents:', f.read())

Debug

Known issues

breakingIn version 2.0.0, the default values for `configure` were changed to `output_az_paths=True` and `save_access_token_to_disk=True`.

fix

Review and adjust your configuration settings if they differ from the new defaults.

affects: >=2.0.0

gotchaAzure Blob Storage does not support multiple writers for the same blob; concurrent writes may lead to `ConcurrentWriteFailure` errors.

fix

Ensure that only one process writes to a blob at a time, or implement a mechanism to handle concurrent writes appropriately.

affects: all

gotchaWhen using `streaming=True` in `BlobFile`, appending to files is not implemented.

fix

Set `streaming=False` if you need to append to files.

affects: all

gotchaThe `glob` function supports glob-style patterns but does not support character ranges.

fix

Avoid using character ranges in glob patterns; use explicit patterns instead.

affects: all

gotchaWhen writing to Azure Blob Storage, the `version` parameter can be used to ensure the remote version matches; mismatches raise a `VersionMismatch` error.

fix

Use the `version` parameter to handle version control during writes to Azure Blob Storage.

affects: >=2.0.2

gotchaOperations can fail with a 403 `RequestFailure` if the configured credentials lack the necessary permissions for the target resource or if the associated cloud project's billing account is disabled.

fix

Ensure that the authentication credentials (e.g., via `GOOGLE_APPLICATION_CREDENTIALS` or `gcloud auth`) grant the required permissions (read/write/list) to the target resource, and verify that the cloud project's billing account is active and enabled.

affects: all

gotchaWriting to Google Cloud Storage (GCS) may fail with `RequestFailure` (status 403) if the associated Google Cloud project's billing account is disabled or if the credentials used do not have sufficient write permissions to the resource.

fix

Ensure that the Google Cloud project associated with the GCS bucket has an active billing account and that the credentials (e.g., `GOOGLE_APPLICATION_CREDENTIALS` environment variable or `gcloud auth application-default login`) grant the necessary write permissions to the target bucket.

affects: all

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'blobfile'

The 'blobfile' library is not installed in the Python environment.

fix

Install the library using pip: `pip install blobfile`

FileNotFoundError: [Errno 2] No such file or directory

The specified file path, whether local or a remote blob storage URL (e.g., `gs://bucket/file` or `az://account/container/file`), does not exist or is inaccessible.

fix

Verify that the file path is correct and that the necessary read permissions are configured for the specified storage location.

Server failed to authenticate the request. Make sure the value of Authorization header is formed correctly including the signature.

Authentication to Google Cloud Storage or Azure Blob Storage failed due to incorrect or expired credentials, misconfigured environment variables (e.g., `GOOGLE_APPLICATION_CREDENTIALS`, `AZURE_STORAGE_KEY`), or insufficient permissions for the storage account/bucket/container.

fix

Ensure that your cloud credentials are correctly set up and have the necessary permissions. For GCS, use `gcloud auth application-default login` or set `GOOGLE_APPLICATION_CREDENTIALS`. For Azure, set `AZURE_STORAGE_KEY` or configure `DefaultAzureCredential` by installing `azure-identity`.

AttributeError: module 'blobfile' has no attribute 'open'

The user is attempting to call `open()` directly on the imported `blobfile` module, instead of using the main `BlobFile` class or its associated functions.

fix

Use `blobfile.BlobFile()` to open files, or one of the other specific functions like `blobfile.exists()`, `blobfile.copy()`, etc.: `import blobfile as bf` followed by `with bf.BlobFile('path/to/file', 'r') as f:`

Upgrade

Version history

3.3.0latest on PyPI · released Aug 20, 2026

Audit

Dependencies

lxmlrequiredXML parsing for Azure Blob Storage operations

pycryptodomexrequiredCryptographic functions for secure operations

filelockrequiredFile locking mechanisms for concurrent access

urllib3requiredHTTP client for making requests to storage services

Agent activity

56 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/blobfile/blobfile ↗

packagehttps://pypi.org/project/blobfile/ ↗