Install & Compatibility
Where this runs
tested against v2026.8.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.95 runs
installs and imports cleanly · install 0.0s · import 1.392s · 58.3MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 6.8s · import 1.272s · 60MB
59MB installed
● package 59MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
AzureBlobFileSystem
✓ from adlfs import AzureBlobFileSystem
This is the primary class for interacting with Azure Blob Storage and ADLS Gen2.
AzureDatalakeFileSystem
✓ from adlfs import AzureDatalakeFileSystem
✗ from adlfs import AzureDatalakeFileSystem
The `AzureDatalakeFileSystem` class and `adl://` protocol were for ADLS Gen1, which is now deprecated and removed. For ADLS Gen2, use `AzureBlobFileSystem` with `abfs://` or `az://` protocols.
This quickstart demonstrates how to initialize `adlfs.AzureBlobFileSystem` and list contents of a public Azure Blob Storage container. For private containers, authentication relies on `storage_options` parameters (like `account_key`, `sas_token`, `connection_string`, or service principal details) or automatic credential resolution via `DefaultAzureCredential` (by setting `anon=False` and ensuring `AZURE_STORAGE_ACCOUNT_NAME` is set).
import os
from adlfs import AzureBlobFileSystem
# Recommended: Use environment variables for credentials
# e.g., AZURE_STORAGE_ACCOUNT_NAME, AZURE_STORAGE_ACCOUNT_KEY, AZURE_STORAGE_SAS_TOKEN
# For DefaultAzureCredential, ensure AZURE_STORAGE_ACCOUNT_NAME is set and anon=False
account_name = os.environ.get('AZURE_STORAGE_ACCOUNT_NAME', 'your_account_name')
# For demonstration, using anonymous access to a public container
# In real scenarios, provide proper credentials (account_key, sas_token, or use anon=False)
fs = AzureBlobFileSystem(account_name=account_name, anon=True)
# Example: List contents of a public container
container_name = "azureopendatastorage" # A known public container
path_to_list = f"az://{container_name}/"
try:
print(f"Listing contents of {path_to_list}:")
contents = fs.ls(path_to_list, detail=False)
for item in contents[:5]: # Print first 5 items
print(item)
if not contents: print("Container is empty or access denied (check credentials/permissions).")
except Exception as e:
print(f"An error occurred: {e}")
print("Please ensure 'AZURE_STORAGE_ACCOUNT_NAME' is set, or if accessing a private container, provide valid credentials.")
# Example: Read a file (requires appropriate permissions)
# Replace with a real path if you have authenticated access
# file_path = f"az://{container_name}/path/to/your/file.txt"
# try:
# with fs.open(file_path, 'rb') as f:
# data = f.read()
# print(f"\nContent of {file_path[:50]}...: {data.decode()[:100]}...")
# except Exception as e:
# print(f"\nCould not read file {file_path[:50]}...: {e}")
Debug
Known issues
breakingADLS Gen1 (adl:// protocol and AzureDatalakeFileSystem class) has been officially retired. Operations using these interfaces are obsolete.fixMigrate to the `az://` or `abfs://` protocols and use the `adlfs.AzureBlobFileSystem` class for Azure Blob Storage and ADLS Gen2.
affects: All versions since 2026.2.0 (deprecation warning since earlier, full removal in future)
breakingStarting in a future release, adlfs will require explicit credentials by default. Anonymous access will no longer be the implicit default.fixIf your application relies on anonymous access, explicitly set `anon=True` when creating `adlfs.AzureBlobFileSystem` instances.
affects: Future releases (warning present since 2026.2.0)
gotchaAuthentication can be complex due to multiple methods (account key, SAS token, service principal, `DefaultAzureCredential`, connection string). Misconfiguring these or incorrect permissions are common issues.fixReview the `adlfs` and Azure SDK documentation for the specific authentication method you intend to use. Ensure all required credentials are provided and have the necessary permissions for the operations. For `DefaultAzureCredential`, ensure `AZURE_STORAGE_ACCOUNT_NAME` is set and `anon=False`.
affects: All versions
breakingSupport for Python 3.9 has been removed.fixUpgrade your Python environment to Python 3.10 or newer.
affects: 2026.2.0 and later
gotchaBy default, write operations create BlockBlobs which cannot be appended to. AppendBlobs (using `mode="ab"`) are also not available if hierarchical namespaces are enabled on the storage account.fixPlan your data ingestion strategy around BlockBlobs for most writes. If appending is critical, verify your storage account configuration and consider alternatives if hierarchical namespaces prevent AppendBlobs.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'adlfs'
The 'adlfs' package is not installed in the Python environment.
fixInstall 'adlfs' using pip: 'pip install adlfs'.
ImportError: cannot import name 'AzureBlobFileSystem' from partially initialized module 'adlfs' (most likely due to a circular import)
A circular import occurs when the script's filename is 'adlfs.py', causing conflicts with the 'adlfs' module.
fixRename the script to avoid naming conflicts with the 'adlfs' module.
ImportError: Install adlfs to access Azure Datalake Gen2 and Azure Blob Storage
The 'adlfs' package is not installed, which is required to access Azure Datalake Gen2 and Azure Blob Storage.
fixInstall 'adlfs' using pip: 'pip install adlfs'.
HttpResponseError: (AuthorizationFailure) This request is not authorized to perform this operation.
The credentials provided (or automatically discovered) do not have sufficient permissions to perform the requested operation on the Azure storage account or container, or there's an issue with token expiration or ACLs.
fixVerify that the Azure Service Principal, Managed Identity, or user account used for authentication has the 'Storage Blob Data Contributor' or 'Storage Blob Data Reader' role (depending on the operation) on the target storage account or container. Ensure that Access Control Lists (ACLs) on specific files or folders do not override these permissions. For long-running operations, ensure token refresh mechanisms are in place or use `DefaultAzureCredential()`.
ValueError: unable to connect to account for Must provide either a connection_string or account_name with credentials!!
When initializing `adlfs.AzureBlobFileSystem` or using `fsspec` with an 'abfs://' or 'az://' URI, the necessary authentication parameters (`account_name`, `account_key`, `sas_token`, `tenant_id`, `client_id`, `client_secret`, or `connection_string`) were not provided or were incorrectly formatted.
fixProvide the required `account_name` and at least one form of credential (e.g., `account_key`, `sas_token`, or service principal details) in the `storage_options` dictionary when instantiating `AzureBlobFileSystem` or passing them to `fsspec`-compatible functions. For public containers, explicitly set `'anon': True`.
Upgrade
Version history
2026.8.0latest on PyPI · released Aug 11, 2026
Audit
Dependencies
fsspecrequiredCore filesystem interface, adlfs is an fsspec implementation.
azure-storage-blobrequiredInternal implementation for Azure Blob Storage operations.
azure-identityoptionalUsed for `DefaultAzureCredential` for authenticated access.
daskoptionalFor Dask integration and distributed data processing.