Install & Compatibility
Where this runs
tested against v0.4.11 · 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.9100 runs
installs and imports cleanly · install 0.0s · import 7.039s · 320.7MB
glibcpy 3.10–3.9100 runs
installs and imports cleanly · install 29.7s · import 6.653s · 323MB
407MB installed
● package 407MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
AzureBlobStorageContainer
✓ from prefect_azure.blob_storage import AzureBlobStorageContainer
AzureBlobStorageCredentials
✓ from prefect_azure import AzureBlobStorageCredentials
blob_storage_download
✓ from prefect_azure.blob_storage import blob_storage_download
AzureContainerInstanceJob
✓ from prefect_azure.container_instance import AzureContainerInstanceJob
This quickstart demonstrates how to download a file from Azure Blob Storage using the `prefect-azure` integration. It highlights the use of `AzureBlobStorageCredentials` and the `blob_storage_download` task. For actual usage, `AZURE_STORAGE_CONNECTION_STRING` should be set as an environment variable or credentials should be managed via Prefect Blocks and Azure's identity features. It also emphasizes the importance of registering Prefect Blocks for discovery.
import os
from prefect import flow
from prefect_azure import AzureBlobStorageCredentials
from prefect_azure.blob_storage import blob_storage_download, AzureBlobStorageContainer
# Before running the flow, ensure the block is registered and saved (e.g., via CLI or a separate script):
# prefect block register -m prefect_azure
# From Python:
# blob_creds = AzureBlobStorageCredentials(connection_string=os.environ.get('AZURE_STORAGE_CONNECTION_STRING', ''))
# blob_creds.save(name="my-blob-creds")
# blob_container_block = AzureBlobStorageContainer(
# container_name="my-container",
# credentials=blob_creds
# )
# blob_container_block.save(name="my-blob-container")
@flow
def example_blob_storage_download_flow():
# Load credentials block (assuming it was saved with 'my-blob-creds')
# In a real scenario, connection_string should be fetched securely (e.g., from Azure Key Vault or Prefect Secret Block)
# or derived from environment variables/managed identity via DefaultAzureCredential.
connection_string = os.environ.get('AZURE_STORAGE_CONNECTION_STRING', '')
if not connection_string:
print("Warning: AZURE_STORAGE_CONNECTION_STRING environment variable not set. Using dummy string.")
# Fallback for example, in real world this would likely fail or use DefaultAzureCredential
blob_storage_credentials = AzureBlobStorageCredentials()
else:
blob_storage_credentials = AzureBlobStorageCredentials(connection_string=connection_string)
# If the AzureBlobStorageContainer block was saved via the UI or another script:
# my_blob_container_block = AzureBlobStorageContainer.load("my-blob-container")
# Instead, we create an ad-hoc one for this example's simplicity
my_blob_container_block = AzureBlobStorageContainer(
container_name="prefect", # Replace with your container name
credentials=blob_storage_credentials
)
print(f"Attempting to download 'prefect.txt' from container 'prefect'...")
data = blob_storage_download(
blob="prefect.txt", # Replace with your blob name
container="prefect", # Or use my_blob_container_block directly if it defines the container
blob_storage_credentials=blob_storage_credentials,
)
print(f"Downloaded data (first 100 chars): {data[:100].decode()}")
return data
if __name__ == "__main__":
# Set a dummy connection string for local testing if not already set
# For actual Azure access, replace with a real connection string or use Azure identity management
# os.environ['AZURE_STORAGE_CONNECTION_STRING'] = 'DefaultEndpointsProtocol=https;AccountName=youraccount;AccountKey=yourkey;EndpointSuffix=core.windows.net'
example_blob_storage_download_flow()
Debug
Known issues
breakingPrefect 2.x (Orion) introduced significant architectural changes, including a new API, flow/task definition patterns using decorators (`@flow`, `@task`), and the 'Block' system for external integrations and credentials. Users migrating from Prefect 1.x will need to refactor flows and task definitions, and adopt the Block pattern for Azure resource configuration.fixRewrite flows and tasks using Prefect 2.x decorators. Migrate old credential management to Prefect Blocks by creating and saving instances of `prefect-azure` Block types (e.g., `AzureBlobStorageCredentials`, `AzureBlobStorageContainer`) via the UI or `block.save()` methods.
affects: <2.0.0 (Prefect core)
gotchaAfter installing `prefect-azure`, its Block types (e.g., `AzureBlobStorageContainer`, `AzureKeyVaultSecret`) must be registered with the Prefect server for them to be discoverable in the UI or by workers. Failing to do so will prevent their use or display.fixRun `prefect block register -m prefect_azure` in your environment after installation. This only needs to be done once per Prefect server instance, or whenever new Block types are added to the collection.
affects: All versions of `prefect-azure` with Prefect 2.x+
gotchaFor secure and robust authentication with Azure services, avoid hardcoding connection strings or secrets. `prefect-azure` components often leverage `azure-identity`'s `DefaultAzureCredential`, which can authenticate via environment variables, managed identities, Azure CLI, etc. Proper Azure RBAC permissions are crucial.fixUtilize Azure Service Principals or Managed Identities configured with appropriate Azure RBAC roles. Store secrets in Azure Key Vault and access them via `prefect-azure`'s Key Vault blocks, or use Prefect's native Secret Blocks. Ensure environment variables like `AZURE_CLIENT_ID`, `AZURE_TENANT_ID`, `AZURE_CLIENT_SECRET` (for service principals) are set, or use Managed Identity.
affects: All versions
gotchaWhen using `AzureBlobStorageContainer` (or similar `prefect-azure` Blocks) as `result_storage` for Prefect flows or tasks, the specific instance of the Block must be saved to the Prefect server (e.g., `block_instance.save("my-block-name")`) before it can be referenced by name in `@flow` or `@task` decorators.fixEnsure the `AzureBlobStorageContainer` Block (or any other Block used as `result_storage`) is saved to the Prefect server. This can be done programmatically using `block.save('block-name')` or via the Prefect UI. The `result_storage` parameter then takes the name of the saved block, e.g., `result_storage=AzureBlobStorageContainer.load("my-block-name")`. affects: All versions of `prefect-azure` with Prefect 2.x+
Errors
Common errors & fixes
AttributeError: 'NoneType' object has no attribute 'rstrip'
This error frequently arises when an Azure Blob Storage connection string or a related configuration (like a container name) is not correctly provided or loaded, causing an attempt to call a string method on a `None` object. This typically happens when `AzureBlobStorageCredentials` or an `Azure` storage block is misconfigured or not found.
fixEnsure all necessary Azure Blob Storage connection strings, container names, and credentials are correctly defined and accessible to your Prefect flow, either directly in code, via Prefect blocks, or as environment variables. Verify the `connection_string` attribute holds a valid string value.
ModuleNotFoundError: No module named 'azure.storage.blob'
The `prefect-azure` library provides integrations but does not automatically install all underlying Azure SDK packages as core dependencies. Specific Azure service interactions, such as with Blob Storage, require their respective SDK packages to be explicitly installed.
fixInstall the required Azure SDK package using pip. For Azure Blob Storage functionality, install `azure-storage-blob` or use the `blob_storage` extra with `prefect-azure`: `pip install "prefect-azure[blob_storage]"`.
RuntimeError: Timed out after ...s while watching waiting for container start.
This timeout occurs when deploying flows to Azure Container Instances (ACI) if the container takes longer than the allotted time to start. Common factors include large Docker image sizes, slow image pulls from the registry, insufficient allocated resources for the ACI instance, network configuration issues preventing access, or incorrect container entry points/commands.
fixIncrease the `task_start_timeout_seconds` in your Azure Container Instance job configuration. Optimize your Docker image to reduce its size, ensure proper network access from ACI to your Azure Container Registry (ACR), and verify the container's startup command and entry point. Consider using a private ACR for faster image pulls.
Flow could not be retrieved from deployment ... IsADirectoryError: [Errno 21] Is a directory
This error sequence indicates that Prefect is attempting to retrieve your flow code from Azure Blob Storage but the configured path points to a directory instead of the specific flow `.py` file. This often happens when the deployment's entrypoint or flow path is configured too broadly.
fixVerify that the `path` or `file_path` in your Azure Blob Storage configuration for flow code (e.g., in `prefect.yaml`) specifies the exact flow `.py` file, not just the parent directory. Ensure your deployment's entrypoint is precise.
Upgrade
Version history
0.4.11latest on PyPI · released Jun 5, 2026
Audit
Dependencies
prefectrequiredCore dependency for Prefect workflow orchestration.
azure-identityrequiredCommon dependency for Azure SDK authentication patterns (e.g., DefaultAzureCredential).
azure-storage-bloboptionalRequired for Azure Blob Storage features (part of `[blob_storage]` extra).
azure-cosmosoptionalRequired for Azure Cosmos DB features (part of `[cosmos_db]` extra).
azureml-fsspecoptionalRequired for Azure ML Datastore features (part of `[ml_datastore]` extra).